Troubleshooting

Troubleshooting

Everything the engine tells you is designed to be actionable. This page decodes the three surfaces you will actually meet: verdicts on the read path, doctor findings, and exit codes — plus the handful of situations new installs hit.

Verdicts are information, not errors

kaut stale exits 0 even when docs are stale — a verdict is data. What to do per verdict:

• stale — sources moved on the main line since the doc's anchor. Run kaut refresh <id>: it hands back the exact changed files (with git status), the sections they hit, and the target commit to re-derive against. Repair, or knowingly read the doc as history.
• branch-advisory — main is clean; your checked-out branch changed bound files. The doc is fine for main-line truth; mind the delta if you are working on that branch.
• broken — a bound source path no longer exists in the anchor tree (renamed file, dead glob). Re-bind the source or re-derive the doc; until then the engine refuses to vouch.
• tampered — the store file differs from the last pipeline commit. Content is withheld, not served. Restore it (git checkout -- <file> inside the store) or land the edit legitimately (kaut index — gate policy applies). This is the injection containment working, not a malfunction.
• miss (unknown id) — exit 0, with nearest-id suggestions. A miss is a coverage signal, not a failure.

Reading doctor

kaut doctor runs the mechanical integrity battery; exit 1 only on FAIL rows.

• store-clean FAIL — uncommitted content in the store (see tampered above).
• index-in-sync FAIL — INDEX.md does not match the docs on disk; run kaut index.
• drafts-pending WARN — the owner has a review queue; kaut review lists it.
• store-identity / store-authors WARN — store git identity or commit authorship differs from the engine's own; informational (authorship is spoofable either way — see SECURITY.md), worth a look if unexpected.
• pointer findings — the repo's .kaut.json disagrees with derivation; harmless to delete the pointer (derivation resolves the same store) or re-run bootstrap.

Multi-repo: kaut doctor --workspace <name> sweeps every store in the registry.

Exit codes

Code	Meaning	Typical cause
0	ok	—
1	validation / doctor failure	contract violation, refused write, FAIL row
2	store busy	another engine process holds the lock (stale locks self-heal: dead pid + 15 min)
3	environment missing	not inside a git repository, or the store is not bootstrapped

First-run situations

• map says "routemap skipped — routes file not found" — the default map globs are stack-conventional; the route collector skips itself on other stacks and the rest still run. Point map.routesFile/map.packagesDir at your files in kaut.config.json, trim map.collectors, or ignore it.
• "not a git repository" — every command runs from inside the project repo (store resolution is cwd-based). Also raised when git itself is not on PATH.
• Write refused ("owner-gated") — the gate is doing its job: queue the update with kaut draft <id> (CLI) / kaut_draft (MCP); the owner lands it via kaut review.
• MCP tools missing in the harness — the server registers as stdio node <engine>/mcp.mjs; after changing registration, restart the harness or reconnect MCP. Details: docs/MCP.md.
• Where is my data? — kaut home prints the current knowledge-data home and where it came from (env / redirect / default); kaut paths prints the full resolution for the current repo.

Still stuck?

docs/OPERATIONS.md covers the on-disk layout and resolution order in full; docs/HANDBOOK.md explains every mechanism. Bugs and questions: open an issue (see CONTRIBUTING.md); suspected vulnerabilities: privately, per SECURITY.md.