Skip to content

Troubleshooting ​

This page lists common errors with their fixes, and the tools for finding out what a run did.

Common problems ​

SymptomCause and fix
VITEST_NOT_FOUNDThe project does not use Vitest. Install it (npm install -D vitest)
CONFIG_MISSINGNo .veritas/config.json. Run veritas init --yes, and commit the file for CI
NO_RUNspec, report, explain and improve read the latest run. Run veritas run first
mutate disabled in doctorVitest is not installed: install the project's dependencies. Mutation testing also needs Vitest 4 or later, and node_modules (not Yarn Plug'n'Play)
Mutation stage failedYour tests fail without any mutant. Make them pass first. If they pass with your own test command, check whether the project has @mizchi/mutator: without it, the copy bundled with Veritas runs the tests with its own Vitest, which cannot load test environments (happy-dom, jsdom) or plugins installed in your project. Add @mizchi/mutator to the project's devDependencies
sandbox is unavailable in doctorNode.js below 25 cannot block network access from project code. Install Node.js 25 or later, or point VERITAS_SANDBOX_NODE at one. sandbox.allowNetworkWithoutIsolation runs the code without blocking
semantic_mismatchThe integer model and JavaScript disagree, for example on values beyond safe integers. Narrow formal.integerDomain, or cover the function with tests
unsupported claimsThe function uses code outside the formal subset; see the support matrix
timeout claimsThe solver hit its time limit. Raise formal.maxSolverMs or narrow formal.integerDomain
error from running out of memoryRaise limits.memoryMb (default 2048 MiB). It applies to project code, the test runner, mutator and Z3
Lean is unavailable in doctorInstall Lean 4 with elan. doctor also looks in ~/.elan/bin
PROPERTY_NOT_FOUND, or an accepted property is proposed againThe file containing the statement changed, so the property has a new ID. Run veritas spec diff and review the new property
APPROVAL_MISMATCHThe token does not belong to the plan, or the plan changed. Run veritas improve --dry-run again and use the new token
IMPROVE_APPLY_IN_CI--apply is refused in CI. Apply locally
IMPROVE_UNSAFE_LINKThe project contains symbolic links pointing outside it. Replace them with real files or directories
A documented rule does not appear in spec listThe rules read threshold phrases only; other statements stay unmapped. An LLM provider can read some of them as proposed properties

See what a run did ​

ToolWhat it shows
--debug or VERITAS_DEBUG=1Debug events on stderr: every child process (command, arguments, working directory, duration, exit code, timeout or kill), restricted calls of project code, stage start and end, cache hits and misses
--log-format jsonThe stderr log as one JSON object per line. stdout is unchanged, so --json output stays pure JSON
.veritas/runs/<run-id>/trace.jsonlThe same events, debug level included, for every run; at most 4 MB, with a final line counting dropped events
veritas replay <run-id>Runs a previous run again with its recorded stages and options
veritas report --run <run-id>The report of a specific run

Logs and traces contain no environment values or file contents, and are redacted.

bash
veritas --debug --log-format json run --profile standard 2> veritas-log.jsonl

Each line of trace.jsonl is one event:

text
{"event":"stage","stage":"discover","at":"start","time":"2026-11-20T10:55:31.938Z","level":"debug","message":"stage discover started"}

replay names the run it repeats before running it:

text
replaying prove from run-20261120T105508829Z-000-017911 (prove --include-proposed)

If your problem is not listed here, open an issue on GitHub with the output of veritas doctor --json and the relevant part of trace.jsonl.

Released under the Apache-2.0 License.