Troubleshoot setup and runs
Start with the installed version and the failing problem:
actinv --version
actinv doctor problem.json
actinv validate problem.json --hashes
doctor reports the working directory, the data directory and where it came from (ACTINV_DATA_DIR or the default ./actinv-data), the catalog version and the cache directory. Without a problem it reports whether the standard data are installed and, if not, the command that installs them; with one it checks that the problem’s input files are readable. Hash validation supplements those checks; evaluated-data compatibility is checked during a run.
| Symptom | Check and action |
|---|---|
actinv command not found | Confirm pip installed into the active Python environment and its scripts directory is on PATH; reopen the terminal after installing |
| Catalog artifact is not installed | Run actinv data fetch in the working folder, or set ACTINV_DATA_DIR to the installation root |
fetch fails with http status: 403 on a decay file | The IAEA site refuses automated downloads. Upgrade to 1.7.2 or later, which falls back to ACTINV’s copy, or install the two decay files by hand as in Install the nuclear data |
| Cannot open a literal data path | Check the current directory for CLI use, Input folder in the desktop, or the problem’s directory for Problem.from_file |
Cannot open <stem>_index.json | Install the activation library and its matching adjacent index together; covariance needs its own index too |
| SHA-256 mismatch | Verify the selected bundle, data path, and library/index pairing; recover the exact declared input rather than removing its hash constraint |
| Covariance does not match activation data | Use the full/full or patched/patched pairing in Data setup |
| Unknown field or invalid composition | Use the specification reference; check spelling, units, isotope aliases, and natural-element/isotope overlaps |
| Positive total with zero spectrum | Supply a nonzero spectrum shape before setting its total flux |
| Projectile, group, or temperature mismatch | Select a compatible library; standard charged-particle libraries use 162 groups and 0 K |
| Missing optional result | Confirm you requested the output and supplied its required data; absence is not a computed zero |
| Browser will not run or fetch data | Use desktop, CLI, or Python for calculations; the browser edits inputs and displays results |
An existing downloaded file is wrong
actinv data verify reports installed-file failures. fetch leaves an incorrect existing file untouched by default. After confirming the intended bundle and destination, request verified replacement:
actinv data fetch --force
actinv data verify
For a custom installation, add --output with its root. For another bundle, name that bundle explicitly.
A prepared cache is corrupt or incompatible
Stop calculations that use the affected cache, then remove the cache artifact or use a new, empty cache directory. ACTINV recreates prepared data from the original inputs. Cache removal affects preparation time; keep your original evaluated data, problems, and results.
Use an absolute ACTINV_CACHE_DIR on a disk with enough space if your normal cache location is unsuitable. Desktop runs use their own private caches.
Small, zero, or unexpected responses
Inspect the ledger for missing material targets, leakage, pruned populations, mode selection, and optional response coverage. Check normalization, irradiation length, cooling time, and the selected library. A missing channel can produce a small prediction without causing a parser error.
Consult Known data limitations before attributing a discrepancy to the solver. Include the software version, a minimal problem, the exact command, and the error message in a bug report. Share data identities or links rather than bulk nuclear-data files.