Troubleshooting
No index
no index in PATH; run: auwai index --repo PATH
Run index or refresh.
The CLI then creates the ledger.
FTS5 is missing
Symptom: no such module: fts5 or an empty query.
Check the Python SQLite build. Use a Python build with FTS5 enabled. The JSONL index still works, but query and retrieval do not.
A query returns nothing
Check the scope first:
./auwai coverage --repo PATH
A partition with unread chunks is a coverage gap. Try a path or symbol term. The index is lexical and does not use embeddings.
A raw read is blocked
The guard is doing its job.
Use auwai read or auwai fullread read.
For a deliberate exception, add this to config.toml:
[guard]
allow_raw_read = true
The watcher does not update
Run one scan:
./auwai watch --repo PATH --once
Then run the audit:
./auwai audit --repo PATH
A branch switch or a large merge may need --repair.
The plan is missing
./auwai fullread plan --repo PATH --context-window N
A new plan keeps the old findings and reads.
The workspace is missing
The workspace manifest lives under .auwai/workspace/workspace.json.
If the root directory was deleted, recreate the workspace and add the repositories again.
The per-repository indexes are separate and can survive.
A database is locked
The ledger uses WAL and a five-second busy timeout. Close another long writer or retry. The watcher and the CLI should not write the same file at once for long.