Troubleshooting#

Solutions to common issues encountered when using NeurEco. For the issues known in this release, see Known Issues.

On this page

Installation Issues#

“NeurEco binaries not found”#

Symptoms:

  • BinaryNotFoundError when creating a model

  • “DLL not found” or “shared library not found” errors

Solutions:

  1. Python package installed with pip: leave dll_path unset: the package uses the binaries it includes. If the error remains, reinstall the package with the PyTorch version and build it requires (see Installation). A GPU edition needs a CUDA build of PyTorch; on Windows, the PyTorch on PyPI is CPU-only.

  2. Installed NeurEco used from Python: set dll_path to the folder that contains the NeurEco libraries, not to a library file. With the default installation folders:

    from NeurEco import NeurEcoTabular as tab

# Windows
model = tab.Regressor(dll_path="C:/Program Files/Adagos/NeurEco-5.0/bin")

# Linux
model = tab.Regressor(dll_path="/opt/neureco/lib")

“No matching distribution found for neureco~=5.0”#

Symptoms:

  • The pip command of your edition stops with No matching distribution found for neureco~=5.0. The line before it may list from versions: 0.0.1: that is a placeholder package on PyPI, not a NeurEco version

Solutions:

  1. Check the Adagos package index in the command against Installation.

  2. Check that pip can reach adagos.com, through your proxy if you use one.

  3. Check that your system is supported: the Python library needs Windows or Linux on x86-64, a 64-bit Python 3.10 or newer, and, on Linux, glibc 2.35 or newer (see Installation). If pip also prints Ignored the following versions that require a different python version, your Python version is too old.

“No matching distribution found for torch<2.9,>=2.8”#

Cause:

The PyTorch version of your edition has no build for your Python version: PyTorch 2.9 supports Python 3.10 to 3.14, and PyTorch 2.7 and 2.8 support Python 3.10 to 3.13. The message gives the PyTorch versions of your edition, for example torch<2.8,>=2.7 for the PyTorch 2.7 edition.

Solution:

Install NeurEco with a Python version that the PyTorch version of your edition supports, for example in a new virtual environment, or choose the PyTorch 2.9 edition.

“No module named ‘NeurEco’” after pip install neureco#

Cause:

pip installed the placeholder package neureco 0.0.1 from PyPI instead of NeurEco: pip show neureco shows that version. pip does so when the command has no Adagos package index, or when pip cannot use it.

Solution:

Run the pip command of your edition given in Installation: it replaces the placeholder. If it stops with No matching distribution found for neureco~=5.0, see that message above.

Python still loads NeurEco 4.x#

Symptoms:

  • After you install NeurEco 5.0 with pip, import NeurEco still loads NeurEco 4.x: features of NeurEco 5.0 are missing, or scripts behave as with NeurEco 4.x

Solution:

The INSTALL.py script of NeurEco 4.x copied the library into Python’s standard-library folder, which Python searches before the packages that pip installs, even in a virtual environment created from that Python. Find and delete that copy as described in Upgrading from the NeurEco 4.x Python Library.

“libgomp not found” (Linux)#

Solution:

The neureco package (DEB or RPM) and the Python package include their OpenMP runtime, so no system OpenMP package is needed. This message points to an incomplete installation: reinstall NeurEco or the Python package (see Installation).

“More than one OpenMP runtime”#

Symptoms:

  • A warning at the start of a build that says OpenMP runtimes are loaded in this process (build log, GUI build output, console), or a Python warning that says More than one OpenMP runtime in this process, followed by the runtime files, for example libiomp5md.dll and libomp.dll from two folders (Windows), or libgomp.so.1 and libomp.so (Linux)

  • Builds much slower than usual, or results that change from one run to the next

Cause:

OpenMP runs NeurEco’s computations on several cores, and each OpenMP runtime manages its own threads. When a second runtime is loaded in the same process, the two compete for the cores, or two copies of the same runtime conflict. The usual source is another library loaded in the same Python session that brings its own OpenMP runtime, such as PyTorch, an MKL-based NumPy or scikit-learn. NeurEco lists MSVC’s vcomp140.dll when it is loaded, but does not count it.

Solutions:

  1. Python package installed with pip: install the PyTorch version that matches your NeurEco package (see Installation).

  2. Installed NeurEco used from Python (dll_path): create the first NeurEco model before importing torch or an MKL-based numpy.

  3. GUI or neureco command: the warning points to an installation problem. Reinstall NeurEco, and do not copy other OpenMP libraries into its folders.

  4. If the warning remains, send its full text to support@adagos.com.

Note

On Windows, the NeurEco Python package sets KMP_DUPLICATE_LIB_OK=TRUE so that a second copy of the Intel or LLVM OpenMP runtime does not stop the process. This hides the conflict but does not solve it: results can then differ between runs. Fix the cause instead.

License Issues#

“License not found”#

Solutions:

  1. Set the ADAGOS_LICENSE_FILE environment variable to the full path of the license file, so that the program you start sees it (see Licensing). On Linux, for example:

    export ADAGOS_LICENSE_FILE="$HOME/adagos.lic"

  2. On Windows, you can instead copy the license file, with its .lic extension, to your user folder (C:\Users\your_username). On Linux, NeurEco does not look in your home directory: without the variable, it finds a license file only in the current folder.

“Feature not licensed”#

You’re trying to use a feature not included in your license (e.g., export formats require an embed license).

Solution: Contact support@adagos.com to upgrade your license.

“License file does not support this version”#

Or, with a license server: “License server system does not support this version of this feature”.

The license was issued for NeurEco 4.5 or 4.6. NeurEco 5.0 needs a license issued for NeurEco 5.0.

Solution: Contact support@adagos.com to replace your license file. If a license server hands out your licenses, its license file must be replaced too.

A “FLEXible License Manager” window opens (Windows)#

On Windows, when a license request is refused, FlexNet, the licensing software that NeurEco uses, shows its own message in a window titled “FLEXible License Manager”. NeurEco waits until you close the window, then shows its own error message.

Solution: Read the message, close the window, and solve the license problem it reports (see the other entries in this section).

“Hardware mismatch”#

Your hardware has changed since the license was generated.

Solution: Generate a new hardware_info.txt in the desktop app (Help menu > Hardware id generator), with the command neureco hardwareinfo, or, with the Python package only, with python -m NeurEco.hardware_info, and send it to support@adagos.com to request a new license.

Data Issues#

“Data contains NaN values”#

Symptoms: DataContainsNaNError

Solutions:

import numpy as np

# Check for NaN
print(f"NaN in X: {np.any(np.isnan(X))}")
print(f"NaN in Y: {np.any(np.isnan(Y))}")

# Option 1: Remove rows with NaN
mask = ~np.isnan(X).any(axis=1) & ~np.isnan(Y).any(axis=1)
X_clean = X[mask]
Y_clean = Y[mask]

# Option 2: Replace NaN with values
X_clean = np.nan_to_num(X, nan=0.0)

“Shape mismatch”#

Symptoms: ArrayShapeMismatchError

Common causes:

  • Input/output sample counts don’t match

  • Wrong number of features for a loaded model

  • Data not properly reshaped to 2D

Solutions:

# Ensure 2D arrays
if len(X.shape) == 1:
    X = X.reshape(-1, 1)

# Check shapes match
print(f"X shape: {X.shape}")
print(f"Y shape: {Y.shape}")
assert X.shape[0] == Y.shape[0], "Sample count mismatch"

# For evaluation, check model expectations
print(f"Model expects {model.get_input_count()} inputs")
print(f"Data has {X.shape[1]} features")

“Empty data”#

Symptoms: DataValidationError mentioning empty arrays

Solution: Verify your data has content:

print(f"X samples: {X.shape[0]}")
assert X.shape[0] > 0, "No samples in input data"

Build Issues#

Build runs indefinitely#

Possible causes:

  • Very large dataset

  • Very complex problem (high-dimensional data)

  • No stopping criteria set

Solutions:

  1. Set maximum neurons:

    config = tab.RegressorBuildConfig(
    input_data=X,
    output_data=Y,
    links_maximum_number=100,  # Limit model size
)

  2. Use checkpointing:

    config = tab.RegressorBuildConfig(
    input_data=X,
    output_data=Y,
    checkpoint_address="./checkpoints/model",
)

    You can stop training and load an intermediate model from the checkpoint.

  3. Reduce data size: Start with a subset to verify the workflow works.

Build produces poor results#

Possible causes:

  • Insufficient or noisy data

  • Inappropriate normalization

  • Problem not suited for NeurEco

Solutions:

  1. Check data quality: Remove outliers, handle missing values

  2. Try different normalization:

    config = tab.RegressorBuildConfig(
    input_data=X,
    output_data=Y,
    inputs_shifting="min_centered",  # or "none", "auto", "mean"
    inputs_scaling="max_centered",   # or "none", "auto", "max", "std"
)

  3. Provide validation data: Explicit validation helps prevent overfitting

    config = tab.RegressorBuildConfig(
    input_data=X_train,
    output_data=Y_train,
    validation_input_data=X_val,
    validation_output_data=Y_val,
)

Evaluation Issues#

“Model not ready”#

Symptoms: ModelNotReadyError

Cause: Trying to evaluate before building or loading a model.

Solution:

from NeurEco import NeurEcoTabular as tab

model = tab.Regressor()

# Either build a new model
model.build(config)

# Or load an existing one
model.load("path/to/model.ednn")

# Now evaluate
predictions = model.evaluate(X)

Wrong output shape (Dynamic)#

Symptoms: Output array has fewer samples than expected

For ConvolutiveDynamic:

Output starts at time step window_size - 1:

# eval_exc has time in its first column; predictions are returned time-first.
predictions = model.evaluate(eval_exc)
w_size = model.get_window_size()

# Align reference with predictions, and drop the prediction's leading time
# column for compute_error (which takes outputs only).
aligned_reference = Y[w_size - 1:]
error = model.compute_error(predictions[:, 1:], aligned_reference)

For ODE with initialization:

The last init point is the first prediction point:

n_init = model.get_number_of_init_tsteps()

# Build time-first arrays (time in the first column).
eval_exc = np.column_stack([time_full, exc_full])
init_exc = np.column_stack([time_full[:n_init], exc_full[:n_init]])
init_out = np.column_stack([time_full[:n_init], out_full[:n_init]])

predictions = model.evaluate(
    eval_exc[n_init - 1:],              # Start from n_init-1; predictions are time-first
    init_excitations=init_exc,
    init_outputs=init_out,
)

Export Issues#

“Export failed”#

Common causes:

  • Missing embed license

  • Invalid export path

  • Incompatible model for format

Solutions:

  1. Check license: Export requires an embed license (e.g., neureco_embed_tabular)

  2. Verify path: Ensure the directory exists and you have write permissions

  3. Check format compatibility:

    Format

    Tabular

    Dynamic

    PFS

    ONNX

    Yes

    No

    No

    FMU

    Yes

    Yes

    Yes

    C Header

    Yes

    No

    No

    VBA

    Yes

    No

    No

CLI Issues#

“Invalid configuration”#

Common causes:

  • JSON syntax error

  • Wrong root key

  • Missing required parameters

Solutions:

  1. Validate JSON: Use a JSON validator to check syntax

  2. Check root key format: Must match template and command, for example neureco Regression build reads:

    {
    "neurecoRegression_build": { ... }
}

  3. Verify required parameters: See CLI Reference for required fields

“File not found”#

Solutions:

  1. Use correct path format:

    • Forward slashes: data/train.csv

    • Or escaped backslashes: data\\train.csv

  2. Check relative paths: they are relative to the folder of the configuration file, not to the folder where the command runs. Use absolute paths if in doubt

  3. Verify files exist before running the command

Memory Issues#

Out of memory during build#

Solutions:

  1. Reduce batch size (if applicable)

  2. Use CPU instead of GPU for very large datasets

  3. Reduce data size: Sample your dataset

  4. Set model size limits:

    config = tab.RegressorBuildConfig(
    input_data=X,
    output_data=Y,
    links_maximum_number=50,
)

Memory not released after delete#

Solution: Always call delete() when done:

model = tab.Regressor()
model.build(config)
predictions = model.evaluate(X_test)

# Free native memory
model.delete()

Getting Help#

If you can’t resolve your issue:

  1. Check the error message: NeurEco provides descriptive error messages

  2. Review the documentation: See the relevant API reference

  3. Contact support: Email support@adagos.com with:

    • NeurEco version

    • Operating system

    • Complete error message

    • Minimal code to reproduce the issue