Troubleshooting¶
The doctor commands¶
doctor engine¶
verlato doctor engine
Reports whether the IntentumDiff engine is linked and its parser bundle found: available,
version, parser_bundle (where it was found), the configured engine, the semantic cache
path and whether cross-file detection is on (semantic_cross_file). error explains what is
missing. The VS Code command Verlato: Show IntentumDiff
Engine Status runs it.
doctor ollama¶
verlato doctor ollama [--warmup] [--parallel-probe] [--suggest-model <model>] [--adaptive-recommendations]
Sends a tiny suggestion-shaped request to the configured Ollama model and reports, as JSON
(schema: "ollama_doctor.v1"):
- the effective configuration (endpoint, model, timeout, keep-alive, context and output caps);
- what Ollama has loaded (
/api/ps, plusollama pswhen theollamacommand is installed), including whether the model runs on CPU or GPU; - for each probe: model load, queue, prompt evaluation and generation time;
- advisory recommendations (client parallelism, keep-alive and warmup, context size, processor placement, output caps).
--warmup loads the model first so the measurement is warm; --parallel-probe sends two
probes at once to see whether Ollama serialises requests (if so, set OLLAMA_NUM_PARALLEL
before starting Ollama). It changes no settings. In VS Code, Model health and Warm
model in the Intent inference panel run it.
doctor model¶
verlato doctor model [--model-provider <name>] [--suggest-model <model>] [--timeout-seconds <s>]
Sends one tiny, diff-shaped structured request to the suggestion model of any provider and
reports whether it answered with valid structured JSON, how long it took and any warnings
(schema: "model_doctor.v1"). Use it to check that a model is capable enough for batched
suggestions before a large run.
Common problems¶
The parser bundle was not found¶
The IntentumDiff engine needs its parser bundle (parser_manifest.json and the *.wasm
parsers). Verlato looks, in order, at VERLATO_INTENTUMDIFF_WASM_DIR, INTENTUMDIFF_WASM_DIR,
then wasm/ next to the executable, ../share/verlato/wasm and ../../wasm relative to it.
The pip package and the release bundles include it, so this usually means a source build:
run scripts/fetch_intentumdiff_parsers.sh, or point VERLATO_INTENTUMDIFF_WASM_DIR at a
bundle. To work without the engine, use --diff-engine git (or VERLATO_DIFF_ENGINE=git).
A file is "not semantically reviewed"¶
The semantic evidence lists every file IntentumDiff could not review, with a kind and the engine's reason, and the changeset is then not reported as completely reviewed:
| Kind | Meaning | What to do |
|---|---|---|
no_parser |
no bundled parser for the file type | nothing; the file still appears in path evidence |
too_large |
the file exceeds the engine's size limits (about 10,000 lines) | raise semantic_max_nodes in verlato.json (or VERLATO_SEMANTIC_MAX_NODES), e.g. 200000 for about 20,000 lines; reviews get slower |
incomplete |
the engine could not explain the whole change, so it is not a clean review | the reason carries the engine's message and a report link; please report it upstream |
pipeline_error |
the engine failed on this file | the reason carries the error |
root-commit |
the first commit has no parent to compare with | nothing |
"Provide --base or one marker mode"¶
Every range command needs a base: --base <ref>, --from-latest-tag or
--from-latest-published. "No reachable tag found" means the repository has no tag yet: use
--base with a commit. "No published release marker found in state" means no release was
recorded with state mark-published yet.
Summaries never come from a model¶
- Check the provider:
verlato doctor model, orverlato doctor ollamafor Ollama. - More changesets than
max_items_per_scan(25) turn model calls off for that scan; raise it or setVERLATO_MODEL_MAX_ITEMS=-1. - Model answers that are empty, error markers or just the title are discarded in favour of
the deterministic summary. Run with
VERLATO_TRACE_MODEL_CALLS=1to see each call on stderr.
Suggestions are slow¶
Run verlato doctor ollama --parallel-probe. Typical fixes: a smaller --suggest-model, a
lean or minimal prompt profile, OLLAMA_NUM_PARALLEL on the server, keeping the model
loaded (VERLATO_OLLAMA_KEEP_ALIVE), and --adaptive-recommendations for advice tailored to
the run. Cached suggestions are reused, so second runs are fast.
A changeset groups unrelated commits¶
Commits outside pull requests are grouped when they share a Conventional Commit type and
scope or touch the same files. Use pull requests or Conventional Commits, or turn on
commit intent inference for vague histories. The
item's grouping_reason says why commits were grouped.
The VS Code extension cannot find Verlato¶
Run Verlato: Show Service Info: it shows the executable in use and every place searched,
and the Verlato output channel says why a verlato on PATH was skipped (a different
version) or why a download failed. Verlato: Download Runtime fetches the runtime again.
Behind a proxy, set VS Code's http.proxy. Otherwise set verlato.cliPath to the verlato
executable, or install it with pip install verlato-core.
Diagnostics¶
| Variable | Shows on stderr |
|---|---|
VERLATO_TRACE_PROGRESS=1 |
[verlato:progress] json {...} progress events |
VERLATO_TRACE_MODEL_CALLS=1 |
[verlato:model] model call lifecycle (also draft suggest --trace-suggestions) |
VERLATO_TRACE_MODEL_PAYLOADS=1 |
full prompts and responses (redacted) |
VERLATO_MODEL_LOG_PATH=<file> |
appends JSONL model telemetry to a file |
See Model telemetry for the formats.
Starting over¶
verlato state clear-working # forget unpublished items and their review decisions
verlato state clear-suggestion-cache # forget cached suggestions
rm .verlato_semantic_cache.json # re-review every commit next time
Reporting a problem¶
Verlato is in beta, and reports help. Open an issue on GitHub using one of the forms:
- Bug report: Verlato failed or did something wrong. Include
verlato --version, how you installed it, and the output ofverlato doctor engine. - Release notes quality: a draft that was wrong or unclear, such as a wrong section, a missed or false
breaking change, or vague wording. Include the item from
verlato draft jsonand what it should have said. - Feature request.
A semantic review that is wrong for a particular language usually belongs to the IntentumDiff engine.