Docs / Guides Build
Troubleshooting
The problems people actually hit, with causes and fixes.
Start with ekos doctor and read .ekos/diagnostics/*.log.
| Symptom | Cause | Fix |
|---|---|---|
0 Table objects but the repo has a schema |
Wrong/missing SQL dialect (whole-file parse failed); only SQL001 warns |
Set [recover.sql] dialect rules |
| 0 Git commits | [observe] paths lists subdirectories; the Git observer needs .git directly under a path |
Use paths = ["."] |
resolve fails: "N identity conflict(s)" |
Conflicting same-name objects across kinds | Review, or ekos resolve --force |
Index is huge / answers cite site-packages |
Vendored code or virtualenvs observed | Add directory names to ignore-patterns; ekos clean; rebuild |
ignore-patterns seems ignored |
Glob used; patterns match directory names | venv, not */venv/* |
ekos ask errors |
No provider or missing key | ekos doctor; set [llm] and the API-key env var |
ekos ask answers cut off |
Reasoning models spend tokens on hidden reasoning | Raise [ai] max-tokens (8192 is a good start) |
| MCP: "search index schema is stale" | Ledger written by a newer version | ekos ledger repair |
| Search finds nothing after upgrade | Stale search index | ekos ledger repair |
commit prompts about LLM spend |
[llm-description] is enabled |
Confirm, pass --yes, or set enabled = false |
Build cannot find cc |
No C toolchain | Install build-essential / Xcode tools / VS Build Tools |
| Secrets appear absent from the index | Working as designed | See Security Model |
Still stuck? Open a discussion with the output of ekos doctor --json.