Skip to content

Troubleshooting

These checks target the published VAMOS 1.4.0 package. See Installation for supported environments and extras, and Stability and versioning for the Stable, Experimental, and Internal labels.

Check the selected environment

Run these commands in the same terminal or notebook environment as your code:

python -c "import sys, vamos; print(sys.executable); print(vamos.__version__); print(vamos.__file__)"
python -m pip show vamos-optimization

The version should be 1.4.0 when following this release's examples. If the package is missing, activate the intended virtual environment and follow Installation. Use python -m pip so installation targets the selected interpreter. Restart a notebook kernel after changing packages.

vamos check provides an additional Experimental diagnostic report. Missing optional packages do not necessarily mean that the core NumPy backend is unusable.

Missing optional dependencies

Install the relevant extra into the active environment; these commands work without a source checkout:

Capability Installation command Status
Numba/MooCore kernels and Dask dependency python -m pip install "vamos-optimization[compute]==1.4.0" Kernel selection is Stable; distributed evaluation is Experimental
Plots and pandas python -m pip install "vamos-optimization[analysis]==1.4.0" Analysis helpers are Experimental
Notebooks python -m pip install "vamos-optimization[analysis,examples]==1.4.0" Experimental
Local Studio python -m pip install "vamos-optimization[studio]==1.4.0" Experimental
Selected domain examples python -m pip install "vamos-optimization[examples]==1.4.0" Check the individual example
Optional tuning backends python -m pip install "vamos-optimization[tuning]==1.4.0" Experimental

VAMOS 1.2.0: the research extra and its third-party baselines are removed, and notebooks need the examples extra besides analysis; see optional extras.

An explicitly requested unavailable backend fails; it is not silently replaced by NumPy. Choose engine="numpy" explicitly if you want a core-only run.

Unknown algorithm, engine, or incompatible encoding

  • Consult the algorithm capability matrix for supported algorithms, encodings, constraints, and backends.
  • Check exact --algorithm and --engine spellings in the CLI reference.
  • Match the problem's encoding with the configured crossover and mutation. The problem catalog documents problem properties.
  • Keep the budget at least as large as the initial population. For reference-direction algorithms, also respect their population/direction cardinality requirements.

Invalid values from a custom problem

Objective values must be finite throughout the declared bounds. Check boundary points explicitly: a denominator must not become zero, and square roots and logarithms must stay in their domains. A batched objective must return an array of shape (batch_size, n_obj).

For constraints, g(x) <= 0 means feasible. Set n_constraints consistently and return the corresponding number of constraint values. See Solving your own problem.

A run or replay destination already exists

Canonical run writers do not overwrite or merge an existing result. Use a new --output-root for a new CLI experiment, a new destination for save_result, or a new --output for replay. Keep existing runs intact when comparing settings. See Run artifacts.

Saving fails on Windows with a long path

Unless long paths are enabled, Windows rejects a path of 260 characters or more (248 for a directory) and reports it as a missing path, with a FileNotFoundError. Saving a run (save_result, reproduce, vamos quickstart) writes through a staging directory next to the destination, which adds about 60 characters to its path. Creating a study adds about 130, because each task lives in tasks/<64-character task hash>/.

VAMOS 1.2.0: when the path is long enough to be the cause, the error gives its length and the ways out listed below. A study reports them in the actual field of its ATOMIC_PUBLICATION_FAILED error, which now also carries the original message. In VAMOS 1.1.0 the error named only the missing path, and a study reported only FileNotFoundError.

  • Enable long paths: set LongPathsEnabled to 1 under HKLM\SYSTEM\CurrentControlSet\Control\FileSystem (administrator rights needed). The "Disable path length limit" option of the Python installer sets it too.
  • Choose a shorter destination.
  • Give the destination as an absolute path with the \\?\ prefix, for example r"\\?\C:\long\path\to\run".

Numba writes its compiled-kernel cache next to the installed package, so in a deeply nested environment its file names can reach the limit too. Set NUMBA_CACHE_DIR to a short directory, such as C:\nbc, before starting Python.

Replay is refused

First inspect and verify the source run:

vamos results inspect results/first-run/ZDT1/nsgaii/numpy/seed_7
vamos results verify results/first-run/ZDT1/nsgaii/numpy/seed_7 --require-level exact

These paths refer to the Minimal Python Track; replace them with your actual run directory. Read the reported integrity, environment, and reconstructability results. Exact replay requires supported built-ins and matching material environment evidence. Loading arrays with load_result is a separate data-only operation and does not require executing the problem. Do not edit manifests to force compatibility.

Benchmark suite names

The benchmark command is Experimental. Use vamos bench --list to discover available suites and match their names exactly. See the CLI reference.