Docs / Reference Operate
Error Codes
Diagnostic codes emitted by the compiler passes and the runtime.
Diagnostics are warnings written to the console summary, to .ekos/diagnostics/*.log and (redacted) to the run log. They do not stop the pipeline unless noted. A live database that cannot be read fails ekos build with the error itself, not a code.
SQL and database
| Code | Emitted by | Meaning | What to do |
|---|---|---|---|
SQL001 |
SQL analyzer | no tables found in a file that states some — almost always the wrong dialect; the message names the dialect | Check [recover.sql] dialect rules |
SQL002 |
SQL analyzer | LLM enrichment output could not be parsed | Structural analysis still applied; retry or raise [llm] max-tokens |
SQL003 |
SQL analyzer | LLM call failed (structural analysis still applied) | Check provider, key, network |
SQL004 |
SQL analyzer | LLM named only some of a file's tables | Raise [llm] max-tokens |
SQL005 |
SQL analyzer | the whole file did not parse, so each statement was tried alone: N of M statements were not parsed and skipped | Usually a dialect feature; check the dialect, or accept the skipped statements |
ORACLE001, PGLIVE001, CHLIVE001 |
live catalog analyzer (Oracle, PostgreSQL, ClickHouse) | a catalog artifact from ekos build could not be read |
Re-run ekos build; a database that cannot be read fails the build itself |
ORACLE002, PGLIVE002, CHLIVE002 |
live catalog analyzer | some views from the catalog could not be parsed; they are counted in the census but have no View object |
ekos database test shows the census next to what was compiled |
CLICKHOUSE001, CLICKHOUSE002 |
ClickHouse analyzer | an artifact could not be read, or its table payload is malformed | Re-run ekos build |
Code and document analyzers
| Code | Emitted by | Meaning | What to do |
|---|---|---|---|
JAVA001, JAVA002 |
Java analyzer | an artifact could not be read, or its payload is malformed | Re-run ekos build |
JAVA003 |
Java analyzer | a file's brackets do not balance; file skipped | Fix or exclude the file |
PYTHON001–003, RUST001–003 |
Python, Rust analyzers | unreadable artifact, malformed payload, a file that cannot be parsed | Re-run ekos build; fix or exclude the file |
JS001–003 |
JavaScript analyzer | unreadable artifact, malformed payload, unrecoverable syntax error | Re-run ekos build; fix or exclude the file |
ELIXIR001–002, PERL001–002 |
Elixir, Perl analyzers | unreadable artifact, malformed payload | Re-run ekos build |
PENTAHO001–003 |
Pentaho analyzer | unreadable artifact, malformed payload, a job or transformation that cannot be parsed | Re-run ekos build; check the file |
GIT001 |
Git analyzer | commit artifact not found in the store | Re-run ekos build; check paths = ["."] |
GIT002 |
Git analyzer | failed to read a commit artifact | ekos clean, rebuild |
GITHUB001–002, CONFLUENCE001–002, LOCALDOCS001–002 |
GitHub, Confluence, local-document analyzers | unreadable artifact, malformed payload | Re-run ekos build |
CRYPTO001–004, GOV001–002, TRS001–002 |
crypto, governance, treasury analyzers | unreadable artifact, malformed payload; for crypto also a relationship to an entity outside its batch, or one without evidence (skipped) | Re-run ekos build |
DOCSEM001–002 |
document semantics | the artifact store cannot be listed, or an artifact is malformed | Re-run ekos recover |
DOCSEM003–004 |
document semantics | an LLM call failed, or its answer could not be parsed; section skipped | Check the provider; retry |
DOCSEM005 |
document semantics | the model named a relationship to a concept absent from its own extraction; skipped | None |
DOCSEM006 |
document semantics | the model's answer was cut off at its output-token limit; section skipped | Raise [llm.tasks.doc-semantics] max-tokens |
ARCHREASON001–002 |
architecture reasoning | the artifact store cannot be listed, or an artifact is malformed | Re-run ekos recover |
ARCHREASON003–004 |
architecture reasoning | an LLM call failed, or its answer could not be parsed; skipped | Check the provider; retry |
ARCHREASON005 |
architecture reasoning | the model named a crate not in the input; rejected | None — the guard worked |
Semantic compiler, conflicts and freshness
| Code | Emitted by | Meaning | What to do |
|---|---|---|---|
SEM000 |
semantic compiler | skipping an unreadable artifact, or no knowledge artifacts found | Run ekos recover first |
SEM001 |
semantic compiler | an identity conflict | Review; resolve --force to continue |
SEM002 |
semantic compiler | a model validation warning — typically a relationship to a File object, which lives in the ledger, not the compiled model. A large estate logs many (about 139k on one, devlog_292); compile counts the expected ones separately |
Usually none |
SEM003 |
semantic compiler | fuzzy same-source merge candidates sent to review as unconfirmed SameAs |
Review with ekos review identity or ekos_identity_review |
CONF001 |
semantic compiler | sources disagree about one fact; both claims kept | ekos conflicts list after commit |
FRESH001 |
compile, commit |
source files changed since ekos build |
Re-run the pipeline from build |
Answer pipeline (ekos ask, ekos_query, ekos_retrieve)
| Code | Meaning |
|---|---|
AI001 |
the model's answer had no valid cited_evidence block |
AI002 |
it had one, but no citation matched evidence actually supplied — treat the answer as ungrounded |
AI003 |
context truncated to stay under the character budget; some neighbourhood objects omitted |
RSN001 |
evidence set truncated to its cap |
RSN002 |
a mention could not be resolved to any object |
RSN003 |
a plan step had no entity to read or no seed to traverse from |
RSN004 |
an object has no fact for the asked attribute |
RSN005 |
info: an aggregate question ("how many …") is better answered by an EKL COUNT / GROUP BY query; the plan falls back to a keyword search |
RSN006 |
no evidence answers the question; refused without calling the model |
RSN007 |
a hub's supporting neighbourhood skipped as too large to be background context |
RSN008 |
sources disagree about a fact and nobody has decided — report both sides |
Integrity finding kinds (ekos check refs, RFC 0233)
Findings are not ledger diagnostics: ekos commit writes them to <state>/integrity/current.json, and ekos check refs recomputes them. Each has a severity (info, warning, error; adjustable in [xref] severity), evidence, a confidence and a fingerprint that survives recompiles.
| Kind | Meaning |
|---|---|
UnresolvedReference |
a name (a table in a Java query, a routine call, an import) that resolves to nothing; the closest names are listed |
AmbiguousReference |
a name that resolves to several objects |
ReferenceCycle |
a dependency cycle between modules |
OrphanArtifact |
an object nothing refers to, such as an unused table |
UnreachableSymbol |
a SQL routine not reachable from any entry point (shown with --reachability) |
DynamicReferenceUnknown |
a reference built at run time that cannot be checked (shown with --reachability) |
Other messages worth knowing
| Message | Meaning |
|---|---|
N identity conflict(s) detected — resolve manually … or pass --force |
ekos resolve failed on conflicts |
search index schema is stale … open writable |
A read-only open of a ledger whose index predates a schema change; run ekos ledger repair |
index runs need rebuilding, which a read-only open cannot do |
Same remedy: one writable command, then reopen |
cannot open fact ledger at … |
Wrong --workspace, or no .ekos/ledger yet |
skipping pass (cached) |
Informational: a pass reused cached output |
N are expected File-object references (compile) |
Not an error: File objects resolve after ekos commit |