Docs / Guides Build
Troubleshooting
The problems people actually hit, with causes and fixes.
Start with ekos doctor, then read .ekos/diagnostics/*.log and the run log of the failing command (.ekos/runs/, or <state>/runs/ for a project in the EKOS home): one JSON line per step with its counts and warnings.
| Symptom | Cause | Fix |
|---|---|---|
0 Table objects (or far too few) but the repo has a schema |
Wrong/missing SQL dialect: statements fail to parse and are skipped (SQL005); SQL001 names the dialect |
Set [recover.sql] dialect rules, or ekos init --detect; check ekos coverage |
| 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 or path used; patterns match directory or file names | venv, not */venv/* |
build fails on a kind = "oracle" database |
Binary built without the oracle feature, or no Instant Client |
cargo build --release -p ekos --features oracle; Instant Client (and libaio.so.1) on LD_LIBRARY_PATH |
ekos database test reports the user can write |
The configured user is not read-only | Use a read-only user; EKOS reports, it does not refuse |
| Census and compiled counts differ | Objects the user cannot see, or the ledger is behind the database | Grant catalog access (Oracle: SELECT_CATALOG_ROLE); rebuild |
FRESH001 at compile/commit |
Source changed after ekos build |
Re-run ekos build first |
Steps 4–7 show blocked |
A step-3 subject has no valid sign-off (missing, stale or revoked) | ekos workflow status, then ekos signoff show <subject> names what changed |
check refs reports tables that exist |
Stale ledger, or a schema EKOS compiled nothing from | Recompile; connect the live catalog with [[databases]] |
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.