EKOSdocs
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.