EKOSdocs
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