Troubleshooting
Every error message mendapi can print, verbatim, with its cause and resolution. Messages are quoted from the shipped code — if you see something not listed here, it did not come from mendapi.
Exit codes at a glance
0— success. Forscanthis includes "impacts found" (a finding is a successful scan, not a failure).1— forfix: nothing applicable (clean repo). Forllmfix/review --llm: LLM configuration missing or invalid. Not an engine failure.2— usage error: bad flags, unknown command/migration, unreadable input file.3—fixrefused a stale pack (see below). Hard stop by design.
Sync & database
"No change database found yet."
From scan: the local SQLite database does not exist. As the message says, run mendapi sync first — the one command that touches the network — then re-run mendapi scan. Exit code is 2.
"error <provider> <repo>: HTTP <status> for <url>"
From sync: one provider feed failed (rate limit, network, upstream outage). Sync continues with the other providers; the failed feed simply is not updated this run. Re-run later. A 403 from api.github.com usually means the anonymous rate limit — wait, or run sync less frequently.
"SQLite is an experimental feature" warning
Printed by Node.js itself for the built-in node:sqlite module, not by mendapi. Harmless. Silence it with NODE_NO_WARNINGS=1 if it bothers your logs.
Fix & migration packs
"Refusing to run migration '<name>': pack needs revalidation."
Exit 3. The upstream API surface this pack targets has newer changes in your database than the pack's recorded baseline — applying it blind could patch against an outdated assumption. The message lists the newer change IDs. Run mendapi revalidate to audit, review the listed changes, then re-run with --ack-stale if the pack is still correct. Never ack blindly.
"Unknown migration: <name>"
Exit 2. Typo or a pack that does not exist in this version. The usage message lists every available migration name; also see Migration Packs.
"Files changed: 0" then exit 1
Not an error. The migration ran and found nothing to change — the repo is clean or already migrated. In CI, treat exit 1 from fix as green (|| test $? -eq 1, see CI & Automation).
"Cannot read impact report: <reason>" / "Impact report has no repo path; pass --repo explicitly." / "Not an impact report: missing impacts[]"
Exit 2. The file passed to --from-report is missing, not JSON, or not a scan report. Regenerate it with mendapi scan --out impact.json (or --json >), and pass --repo when the report was produced elsewhere.
BYO LLM configuration
All LLM features are opt-in; these errors only appear when you ask for them (llmfix, review --llm).
"No LLM provider configured. mendapi works without one (deterministic rule packs); ..."
Set MENDAPI_LLM_PROVIDER to openai, anthropic, or openai-compatible. Or simply do not use the --llm features — everything else is rule-based. Exit 1.
"Provider "<name>" requires an API key. Set MENDAPI_LLM_API_KEY (your key stays on your machine)."
openai and anthropic need a key. openai-compatible (local endpoints like Ollama/vLLM) does not, but requires MENDAPI_LLM_BASE_URL. See BYO LLM for full setup.
"Provider ... requires a base URL." / "Invalid base URL ..." / "... requires a model name. Set MENDAPI_LLM_MODEL."
Config validation, fail-loud before any network call. Base URLs must start with http:// or https://; every provider needs an explicit MENDAPI_LLM_MODEL.
"LLM endpoint <url> returned HTTP <status>: ..." / "LLM endpoint returned non-JSON response body" / "LLM response contained no text content"
Transport-level failures from your endpoint: wrong key (401), wrong path in the base URL (404), overloaded backend (429/5xx), or a proxy returning HTML. Fix the endpoint; mendapi will not retry silently.
"change=... file=...: updated content fails syntax check — dropped (fail conservative)"
llmfix drafted a patch whose resulting file does not parse, so it was discarded rather than saved. Same policy for "unparseable LLM response" and "model declined": bad drafts are dropped, never written. Re-run, try a stronger model, or handle that change manually. Drafts are previews — llmfix never modifies your repo either way.
Review
"skip change_id=...: not in report" / "skip change_id=...: confidence=high not reviewable"
Verdicts only apply to medium-confidence impacts present in the report. High-confidence findings are evidence-gated and not LLM-overridable; unknown IDs are skipped and counted.
"Verdicts must be a non-empty JSON array." / "invalid verdict: ..."
The --verdicts file must be a JSON array of {change_id, verdict, rationale} objects, with verdict one of confirm, unlikely, or keep. Get the expected input from review --pending first.
MCP server
Tool result has isError: true
Tool-level failure (unknown tool, missing required argument, nonexistent repo path). The error text explains which. The server stays alive — fix the call and retry.
JSON-RPC error -32601 / -32700
Unknown method / malformed JSON line. Protocol-level, per-request; the server keeps serving subsequent requests. Make sure your client speaks newline-delimited JSON-RPC 2.0 over stdio.
Scan output looks wrong
Scan reports 0 impacts but I use these providers
Check providers_detected in the summary line first. If your provider is missing, the scanner found no import/require/API-host evidence for it — scan runs on static code, so dynamically-constructed imports are invisible by design. If the provider is detected but impacts are 0, the recorded changes genuinely do not touch symbols in your files.
Scan flags code in a monorepo package I do not use
Findings are evidence-gated per file. If a hit looks wrong, its usage_sites carry the exact file:line evidence — check whether that file really references the changed symbol. Report shape is documented field-by-field in the CLI reference.