The canonical error registry and its headless exit-code mapping.
Every canonic error carries a stable, wire-safe code string plus a headless process exit code, never free text alone, so a caller (script, CI job, agent) can act on it programmatically. The registry lives in canonic/exc.py and is guarded by conformance tests, so this mapping can’t silently drift.
Exit code
code
Meaning
2
unresolved
A metric name matches no active canonical binding.
3
ambiguous
A name matches more than one active binding. Candidates are returned.
4
unreachable
A dimension/filter has no declared join path to the metric’s source.
5
ambiguous_join_path
More than one valid join path exists. The query must name an explicit via.
6
unsupported_measure
A non-additive/semi-additive measure was requested at a grain no strategy can safely serve.
7
fanout_unsafe
A join would corrupt a non-additive measure.
8
guardrail_block
A severity: error guardrail blocked the query.
9
validation_failed
A semantic/contract/knowledge file failed validation.
10
assertion_failed
An assertion diverged from its expected value beyond tolerance (also used by canonic assert’s --min-accuracy gate).
11
read_only_violation
A non-SELECT statement was submitted to a read-only execution path.
12
schema_mismatch
Declared schema doesn’t match the live source during probe validation.
13
connection_error
A connector couldn’t establish or maintain a connection (also raised for an unregistered connector type, or an out-of-range connector version).
14
contradiction
Headless --strict ingest found a run with any flagged contradiction.
15
generation_failed
An LLM generation call failed (deterministic provider/transport error).
16
structured_output_invalid
The model’s output doesn’t satisfy the requested JSON schema.
17
structured_output_unsupported
The model/endpoint can’t honor schema-constrained output at all.
18
air_gapped_violation
Air-gapped mode would let context leave the machine (public endpoint, remote secret ref, or telemetry).
19
retries_exhausted
A transient provider/transport failure persisted past the bounded retry budget.
20
telemetry_not_configured
A real telemetry send was attempted without enabled/endpoint/transport_acknowledged all set.
21
telemetry_send_failed
The telemetry HTTP call itself failed (non-2xx, connection error, timeout).
22
tenant_unresolved
A tenancy policy is active but the request carries no resolvable tenant. Raised at compiler stage 0, before metric resolution.
23
tenant_scope_missing
A query reaches a source declared in neither scoped_sources nor shared_sources of the tenancy policy: a policy hole, not an unfiltered pass-through.
24
tenant_forbidden
The caller’s own policy denies something the caller can already see: run_sql denied by role, or run_sql refused because the connection lacks rls_enforced: true under an active tenancy policy.
25
tenant_limit_exceeded
A principal’s tenant claim holds more distinct values than mcp.auth.max_tenants. Raised while the principal is bound from the token, before any SQL is compiled.
26
period_open
decompose was asked to compare a period that has not ended at the serving clock (or as_of). Set allow_open_period: true to decompose it anyway.
27
decomposition_inconsistent
The declared numerator_parts of a metric do not sum to its numerator in one of the compared periods: a contract bug that a decomposition would hide.
28
capability_disabled
A capability was called that the project config switches off, such as decompose under decompose.enabled: false.
Resolving ambiguous
When a name matches more than one active binding, the error carries a candidates list: the exact, unambiguous values to re-issue the request with. Both --json and plain-text CLI output, and the MCP tool error payload, include it.Ambiguous dimension: a dimension name is declared on more than one join-reachable source (e.g. country exists on both customers and a twice-joined locations, reached as pickup/dropoff):
canonic query --metrics rental_revenue --dimensions country
error ambiguous: dimension 'country' is present on multiple join-reachable sources; qualify explicitly candidate 1: customers.country candidate 2: dropoff.country candidate 3: locations.country candidate 4: pickup.country hint: qualify with one of the candidates above, e.g. --dimensions customers.country
Qualify with alias.dimension: the alias is the join’s name (or the source name for an unnamed join). To pick the one you mean:
Ambiguous metric name: two active bindings share a name/alias. The candidates list names each competing metric. Re-issue with the specific canonical name (or fix the duplicate alias in contracts/metrics/) rather than the ambiguous shared one.
Resolving tenant_unresolved
A tenancy policy is loaded, but the request carries no resolvable tenant, most commonly a stdio MCP session with no --tenant flag, or a bearer token whose claims don’t carry the tenancy policy’s claim:
canonic query --metrics revenue
error tenant_unresolved: tenancy policy is active but the request carries no resolvable tenant
Fix it with --tenant for local development (always warns, see --tenant CLI override), or by confirming the token actually carries the configured claim. A tenant claim that is an empty list, or a list of only null or blank values, counts as missing. So does a value that cannot be a tenant identifier, such as a boolean or an object, and a value that does not fit an integer scope column:
canonic query --metrics revenue --tenant 4711
Setting on_missing_principal: allow_unscoped in tenancy.yaml avoids the error entirely and serves unscoped with a warning instead, a dev-only escape hatch, not a production setting.
Resolving tenant_scope_missing
A query’s join plan reaches a source declared in neither scoped_sources nor shared_sources of the tenancy policy. This is a policy hole the compiler refuses to serve unfiltered, not a bug to silently work around:
error tenant_scope_missing: source 'shipments' is declared in neither scoped_sources nor shared_sources of the tenancy policy
Fix it by classifying shipments in tenancy.yaml: as scoped_sources (add its tenant column) if it carries per-tenant rows, or shared_sources if it’s genuinely tenant-neutral (a lookup/dimension table). Setting undeclared_source: warn turns this into a warning instead of a hard failure, useful only for incremental adoption on an existing project. It still means the source is served unfiltered in the meantime.
Resolving tenant_limit_exceeded
A token’s tenant claim lists more distinct tenants than mcp.auth.max_tenants allows (default 100):
error tenant_limit_exceeded: tenant claim carries 140 distinct values, more than the allowed 100 (mcp.auth.max_tenants)
Either trim the list at the identity provider, or raise mcp.auth.max_tenants in canonic.yaml if the larger list is intended. Each tenant adds a value to the IN (...) predicate on every scoped source, so the limit also bounds the size of the compiled SQL.
Resolving tenant_forbidden
Raised only by the run_sql gate, for one of two independent reasons:
error tenant_forbidden: role denies raw SQL execution (run_sql: false)
The caller’s role doesn’t grant run_sql: true. No connection-level fix resolves this: the role itself has to change.
error tenant_forbidden: run_sql is refused on connection 'warehouse_pg': a tenancy policy is active and this connection carries no rls_enforced: true attestation
Tenancy is active, the caller isn’t tenancy_exempt, and the target connection has no rls_enforced: true in canonic.yaml. Fix it by setting rls_enforced: true, but only once the warehouse actually enforces the tenant boundary out of band (per-tenant credentials or native row-level security). Setting the flag without the enforcement behind it defeats the point of the gate.
Errors without a registry code
A few internal/caller-contract errors carry no wire ErrorCode and use the default exit code 1: CapabilityNotSupportedError (a connector was asked to honor a capability it doesn’t declare), EmbeddingUnavailable (embed called without gating on is_available()), CredentialError, SemanticSourceError, ContractError, and KnowledgePageError. These signal a caller/config mistake rather than a documented, structured failure mode.
EvalDatasetError (a malformed canonic eval baseline dataset/candidates file) and KnowledgeReferenceError (a broken sl_ref/page link) both reuse validation_failed (exit 9) rather than defining new codes. They’re the same class of failure as any other invalid input file.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"canonic","description":"The Open Context Layer for Data Agents","colors":{"primary":"#0F766E","light":"#14B8A6","dark":"#0F766E"},"favicon":"https://mintcdn.com/canonic/xcMqNz1DyuYnUSDg/favicon.svg?fit=max\u0026auto=format\u0026n=xcMqNz1DyuYnUSDg\u0026q=85\u0026s=693b6661e535b4ab17f9341e5c1a358e","navbar":{"links":[{"href":"https://www.getcanonic.app","label":"Home"},{"href":"https://github.com/mischuh/canonic","type":"github"}]},"seo":{"metatags":{"og:image":"https://docs.getcanonic.app/og-image.png","twitter:image":"https://docs.getcanonic.app/og-image.png"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"canonic","hasAudioNarration":false,"actualSubdomain":"canonic","customDomains":["docs.getcanonic.app"],"gitSource":{"type":"github","owner":"mischuh","repo":"canonic","deployBranch":"main","contentDirectory":"docs","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6aeb831c66102287f8a03adf","clientVersion":"0.0.4227","searchFilterCounts":[{"language":"default","tag":"CLI Reference","count":15},{"language":"default","tag":"Guides","count":14},{"language":"default","tag":"Concepts","count":10},{"language":"default","tag":"Compare","count":6},{"language":"default","tag":"Reference","count":6},{"language":"default","tag":"Getting Started","count":5},{"language":"default","tag":"MCP / Agent Integration","count":2}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"reference/error-codes","slug":"/reference/error-codes","pageMetadata":{"title":"Error codes","description":"The canonical error registry and its headless exit-code mapping.","href":"/reference/error-codes"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"The canonical error registry and its headless exit-code mapping.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{CodeBlock,Heading,Note,Table}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Note)_missingMdxReference(`Note`,true);if(!Table)_missingMdxReference(`Table`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Every canonic error carries a stable, wire-safe `,_jsx(_components.code,{children:`code`}),` string plus a headless process exit code, never free text alone, so a caller (script, CI job, agent) can act on it programmatically. The registry lives in `,_jsx(_components.code,{children:`canonic/exc.py`}),` and is guarded by conformance tests, so this mapping can’t silently drift.`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Exit code`}),_jsx(_components.th,{children:_jsx(_components.code,{children:`code`})}),_jsx(_components.th,{children:`Meaning`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`2`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`unresolved`})}),_jsx(_components.td,{children:`A metric name matches no active canonical binding.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`3`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`ambiguous`})}),_jsx(_components.td,{children:`A name matches more than one active binding. Candidates are returned.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`4`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`unreachable`})}),_jsx(_components.td,{children:`A dimension/filter has no declared join path to the metric’s source.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`5`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`ambiguous_join_path`})}),_jsxs(_components.td,{children:[`More than one valid join path exists. The query must name an explicit `,_jsx(_components.code,{children:`via`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`6`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`unsupported_measure`})}),_jsx(_components.td,{children:`A non-additive/semi-additive measure was requested at a grain no strategy can safely serve.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`7`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`fanout_unsafe`})}),_jsx(_components.td,{children:`A join would corrupt a non-additive measure.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`8`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`guardrail_block`})}),_jsxs(_components.td,{children:[`A `,_jsx(_components.code,{children:`severity: error`}),` guardrail blocked the query.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`9`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`validation_failed`})}),_jsx(_components.td,{children:`A semantic/contract/knowledge file failed validation.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`10`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`assertion_failed`})}),_jsxs(_components.td,{children:[`An assertion diverged from its expected value beyond tolerance (also used by `,_jsx(_components.code,{children:`canonic assert`}),`’s `,_jsx(_components.code,{children:`--min-accuracy`}),` gate).`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`11`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`read_only_violation`})}),_jsxs(_components.td,{children:[`A non-`,_jsx(_components.code,{children:`SELECT`}),` statement was submitted to a read-only execution path.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`12`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`schema_mismatch`})}),_jsx(_components.td,{children:`Declared schema doesn’t match the live source during probe validation.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`13`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`connection_error`})}),_jsxs(_components.td,{children:[`A connector couldn’t establish or maintain a connection (also raised for an unregistered connector `,_jsx(_components.code,{children:`type`}),`, or an out-of-range connector version).`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`14`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`contradiction`})}),_jsxs(_components.td,{children:[`Headless `,_jsx(_components.code,{children:`--strict`}),` ingest found a run with any flagged contradiction.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`15`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`generation_failed`})}),_jsx(_components.td,{children:`An LLM generation call failed (deterministic provider/transport error).`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`16`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`structured_output_invalid`})}),_jsx(_components.td,{children:`The model’s output doesn’t satisfy the requested JSON schema.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`17`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`structured_output_unsupported`})}),_jsx(_components.td,{children:`The model/endpoint can’t honor schema-constrained output at all.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`18`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`air_gapped_violation`})}),_jsx(_components.td,{children:`Air-gapped mode would let context leave the machine (public endpoint, remote secret ref, or telemetry).`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`19`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`retries_exhausted`})}),_jsx(_components.td,{children:`A transient provider/transport failure persisted past the bounded retry budget.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`20`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`telemetry_not_configured`})}),_jsxs(_components.td,{children:[`A real telemetry send was attempted without `,_jsx(_components.code,{children:`enabled`}),`/`,_jsx(_components.code,{children:`endpoint`}),`/`,_jsx(_components.code,{children:`transport_acknowledged`}),` all set.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`21`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`telemetry_send_failed`})}),_jsx(_components.td,{children:`The telemetry HTTP call itself failed (non-2xx, connection error, timeout).`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`22`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`tenant_unresolved`})}),_jsxs(_components.td,{children:[`A `,_jsx(_components.a,{href:`/concepts/tenancy-and-access-control`,children:`tenancy policy`}),` is active but the request carries no resolvable tenant. Raised at compiler stage 0, before metric resolution.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`23`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`tenant_scope_missing`})}),_jsxs(_components.td,{children:[`A query reaches a source declared in neither `,_jsx(_components.code,{children:`scoped_sources`}),` nor `,_jsx(_components.code,{children:`shared_sources`}),` of the tenancy policy: a policy hole, not an unfiltered pass-through.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`24`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`tenant_forbidden`})}),_jsxs(_components.td,{children:[`The caller’s own policy denies something the caller can already see: `,_jsx(_components.code,{children:`run_sql`}),` denied by role, or `,_jsx(_components.code,{children:`run_sql`}),` refused because the connection lacks `,_jsx(_components.code,{children:`rls_enforced: true`}),` under an active tenancy policy.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`25`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`tenant_limit_exceeded`})}),_jsxs(_components.td,{children:[`A principal’s tenant claim holds more distinct values than `,_jsx(_components.code,{children:`mcp.auth.max_tenants`}),`. Raised while the principal is bound from the token, before any SQL is compiled.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`26`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`period_open`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`decompose`}),` was asked to compare a period that has not ended at the serving clock (or `,_jsx(_components.code,{children:`as_of`}),`). Set `,_jsx(_components.code,{children:`allow_open_period: true`}),` to decompose it anyway.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`27`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`decomposition_inconsistent`})}),_jsxs(_components.td,{children:[`The declared `,_jsx(_components.code,{children:`numerator_parts`}),` of a metric do not sum to its numerator in one of the compared periods: a contract bug that a decomposition would hide.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`28`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`capability_disabled`})}),_jsxs(_components.td,{children:[`A capability was called that the project config switches off, such as `,_jsx(_components.code,{children:`decompose`}),` under `,_jsx(_components.code,{children:`decompose.enabled: false`}),`.`]})]})]})]}),`\n`,_jsxs(Heading,{level:`2`,id:`resolving-ambiguous`,children:[`Resolving `,_jsx(_components.code,{children:`ambiguous`})]}),`\n`,_jsxs(_components.p,{children:[`When a name matches more than one active binding, the error carries a `,_jsx(_components.code,{children:`candidates`}),` list: the exact, unambiguous values to re-issue the request with. Both `,_jsx(_components.code,{children:`--json`}),` and plain-text CLI output, and the MCP tool error payload, include it.`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Ambiguous dimension`}),`: a dimension name is declared on more than one join-reachable source (e.g. `,_jsx(_components.code,{children:`country`}),` exists on both `,_jsx(_components.code,{children:`customers`}),` and a twice-joined `,_jsx(_components.code,{children:`locations`}),`, reached as `,_jsx(_components.code,{children:`pickup`}),`/`,_jsx(_components.code,{children:`dropoff`}),`):`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`canonic`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` query`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --metrics`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` rental_revenue`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --dimensions`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` country`})]}),`\n`]})})}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`7`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`7`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`error ambiguous: dimension 'country' is present on multiple join-reachable sources; qualify explicitly`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` candidate 1: customers.country`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` candidate 2: dropoff.country`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` candidate 3: locations.country`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` candidate 4: pickup.country`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` hint: qualify with one of the candidates above, e.g. --dimensions customers.country`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[`Qualify with `,_jsx(_components.code,{children:`alias.dimension`}),`: the alias is the join’s `,_jsx(_components.code,{children:`name`}),` (or the source name for an unnamed join). To pick the one you mean:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`canonic`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` query`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --metrics`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` rental_revenue`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --dimensions`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` customers.country`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Ambiguous metric name`}),`: two active bindings share a name/alias. The `,_jsx(_components.code,{children:`candidates`}),` list names each competing metric. Re-issue with the specific canonical name (or fix the duplicate alias in `,_jsx(_components.code,{children:`contracts/metrics/`}),`) rather than the ambiguous shared one.`]}),`\n`,_jsxs(Heading,{level:`2`,id:`resolving-tenant_unresolved`,children:[`Resolving `,_jsx(_components.code,{children:`tenant_unresolved`})]}),`\n`,_jsxs(_components.p,{children:[`A `,_jsx(_components.a,{href:`/concepts/tenancy-and-access-control`,children:`tenancy policy`}),` is loaded, but the request carries no resolvable tenant, most commonly a `,_jsx(_components.code,{children:`stdio`}),` MCP session with no `,_jsx(_components.code,{children:`--tenant`}),` flag, or a bearer token whose claims don’t carry the tenancy policy’s `,_jsx(_components.code,{children:`claim`}),`:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`canonic`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` query`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --metrics`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` revenue`})]}),`\n`]})})}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`2`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`error tenant_unresolved: tenancy policy is active but the request carries no resolvable tenant`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[`Fix it with `,_jsx(_components.code,{children:`--tenant`}),` for local development (always warns, see `,_jsxs(_components.a,{href:`/concepts/tenancy-and-access-control#--tenant-cli-override`,children:[_jsx(_components.code,{children:`--tenant`}),` CLI override`]}),`), or by confirming the token actually carries the configured `,_jsx(_components.code,{children:`claim`}),`. A tenant claim that is an empty list, or a list of only null or blank values, counts as missing. So does a value that cannot be a tenant identifier, such as a boolean or an object, and a value that does not fit an integer scope column:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`canonic`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` query`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --metrics`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` revenue`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --tenant`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 4711`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Setting `,_jsx(_components.code,{children:`on_missing_principal: allow_unscoped`}),` in `,_jsx(_components.code,{children:`tenancy.yaml`}),` avoids the error entirely and serves unscoped with a warning instead, a dev-only escape hatch, not a production setting.`]}),`\n`,_jsxs(Heading,{level:`2`,id:`resolving-tenant_scope_missing`,children:[`Resolving `,_jsx(_components.code,{children:`tenant_scope_missing`})]}),`\n`,_jsxs(_components.p,{children:[`A query’s join plan reaches a source declared in neither `,_jsx(_components.code,{children:`scoped_sources`}),` nor `,_jsx(_components.code,{children:`shared_sources`}),` of the tenancy policy. This is a policy hole the compiler refuses to serve unfiltered, not a bug to silently work around:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`2`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`error tenant_scope_missing: source 'shipments' is declared in neither scoped_sources nor shared_sources of the tenancy policy`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[`Fix it by classifying `,_jsx(_components.code,{children:`shipments`}),` in `,_jsx(_components.code,{children:`tenancy.yaml`}),`: as `,_jsx(_components.code,{children:`scoped_sources`}),` (add its tenant column) if it carries per-tenant rows, or `,_jsx(_components.code,{children:`shared_sources`}),` if it’s genuinely tenant-neutral (a lookup/dimension table). Setting `,_jsx(_components.code,{children:`undeclared_source: warn`}),` turns this into a warning instead of a hard failure, useful only for incremental adoption on an existing project. It still means the source is served unfiltered in the meantime.`]}),`\n`,_jsxs(Heading,{level:`2`,id:`resolving-tenant_limit_exceeded`,children:[`Resolving `,_jsx(_components.code,{children:`tenant_limit_exceeded`})]}),`\n`,_jsxs(_components.p,{children:[`A token’s tenant claim lists more distinct tenants than `,_jsx(_components.code,{children:`mcp.auth.max_tenants`}),` allows (default `,_jsx(_components.code,{children:`100`}),`):`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`2`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`error tenant_limit_exceeded: tenant claim carries 140 distinct values, more than the allowed 100 (mcp.auth.max_tenants)`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[`Either trim the list at the identity provider, or raise `,_jsx(_components.code,{children:`mcp.auth.max_tenants`}),` in `,_jsx(_components.code,{children:`canonic.yaml`}),` if the larger list is intended. Each tenant adds a value to the `,_jsx(_components.code,{children:`IN (...)`}),` predicate on every scoped source, so the limit also bounds the size of the compiled SQL.`]}),`\n`,_jsxs(Heading,{level:`2`,id:`resolving-tenant_forbidden`,children:[`Resolving `,_jsx(_components.code,{children:`tenant_forbidden`})]}),`\n`,_jsxs(_components.p,{children:[`Raised only by the `,_jsxs(_components.a,{href:`/concepts/tenancy-and-access-control#the-run_sql-gate`,children:[_jsx(_components.code,{children:`run_sql`}),` gate`]}),`, for one of two independent reasons:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`2`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`error tenant_forbidden: role denies raw SQL execution (run_sql: false)`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[`The caller’s role doesn’t grant `,_jsx(_components.code,{children:`run_sql: true`}),`. No connection-level fix resolves this: the role itself has to change.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`2`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`error tenant_forbidden: run_sql is refused on connection 'warehouse_pg': a tenancy policy is active and this connection carries no rls_enforced: true attestation`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[`Tenancy is active, the caller isn’t `,_jsx(_components.code,{children:`tenancy_exempt`}),`, and the target connection has no `,_jsx(_components.code,{children:`rls_enforced: true`}),` in `,_jsx(_components.code,{children:`canonic.yaml`}),`. Fix it by setting `,_jsx(_components.code,{children:`rls_enforced: true`}),`, but only once the warehouse actually enforces the tenant boundary out of band (per-tenant credentials or native row-level security). Setting the flag without the enforcement behind it defeats the point of the gate.`]}),`\n`,_jsx(Heading,{level:`2`,id:`errors-without-a-registry-code`,children:`Errors without a registry code`}),`\n`,_jsxs(_components.p,{children:[`A few internal/caller-contract errors carry no wire `,_jsx(_components.code,{children:`ErrorCode`}),` and use the default exit code `,_jsx(_components.strong,{children:`1`}),`: `,_jsx(_components.code,{children:`CapabilityNotSupportedError`}),` (a connector was asked to honor a capability it doesn’t declare), `,_jsx(_components.code,{children:`EmbeddingUnavailable`}),` (embed called without gating on `,_jsx(_components.code,{children:`is_available()`}),`), `,_jsx(_components.code,{children:`CredentialError`}),`, `,_jsx(_components.code,{children:`SemanticSourceError`}),`, `,_jsx(_components.code,{children:`ContractError`}),`, and `,_jsx(_components.code,{children:`KnowledgePageError`}),`. These signal a caller/config mistake rather than a documented, structured failure mode.`]}),`\n`,_jsx(Note,{children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`EvalDatasetError`}),` (a malformed `,_jsx(_components.code,{children:`canonic eval baseline`}),` dataset/candidates file) and `,_jsx(_components.code,{children:`KnowledgeReferenceError`}),` (a broken `,_jsx(_components.code,{children:`sl_ref`}),`/page link) both reuse `,_jsx(_components.code,{children:`validation_failed`}),` (exit 9) rather than defining new codes. They’re the same class of failure as any other invalid input file.`]})})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Error codes","description":"The canonical error registry and its headless exit-code mapping.","href":"/reference/error-codes"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Resolving ambiguous","slug":"resolving-ambiguous","depth":2,"children":[]},{"title":"Resolving tenant_unresolved","slug":"resolving-tenant_unresolved","depth":2,"children":[]},{"title":"Resolving tenant_scope_missing","slug":"resolving-tenant_scope_missing","depth":2,"children":[]},{"title":"Resolving tenant_limit_exceeded","slug":"resolving-tenant_limit_exceeded","depth":2,"children":[]},{"title":"Resolving tenant_forbidden","slug":"resolving-tenant_forbidden","depth":2,"children":[]},{"title":"Errors without a registry code","slug":"errors-without-a-registry-code","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"canonic","siteName":"canonic","title":"Error codes - canonic","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-19T11:43:39.663Z","originalFileLocation":"reference/error-codes.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"The canonical error registry and its headless exit-code mapping.\">\u003cmeta data-mint-head name=\"application-name\" content=\"canonic\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/canonic/MolZOS0pjh0XFsG7/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/canonic/MolZOS0pjh0XFsG7/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/canonic/MolZOS0pjh0XFsG7/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/canonic/MolZOS0pjh0XFsG7/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/canonic/MolZOS0pjh0XFsG7/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/canonic/MolZOS0pjh0XFsG7/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/canonic/MolZOS0pjh0XFsG7/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/canonic/MolZOS0pjh0XFsG7/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/canonic/MolZOS0pjh0XFsG7/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Error codes - canonic\">\u003cmeta data-mint-head property=\"og:description\" content=\"The canonical error registry and its headless exit-code mapping.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"canonic\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.getcanonic.app/reference/error-codes\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://docs.getcanonic.app/og-image.png\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Error codes - canonic\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"The canonical error registry and its headless exit-code mapping.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://docs.getcanonic.app/og-image.png\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/canonic/MolZOS0pjh0XFsG7/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"canonic\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0F766E\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.getcanonic.app/reference/error-codes\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/reference/error-codes.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.getcanonic.app/#organization\",\"name\":\"canonic\",\"url\":\"https://docs.getcanonic.app\"},{\"@type\":\"WebSite\",\"@id\":\"https://docs.getcanonic.app#website\",\"name\":\"canonic\",\"url\":\"https://docs.getcanonic.app\",\"publisher\":{\"@id\":\"https://docs.getcanonic.app/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.getcanonic.app/reference/error-codes#webpage\",\"url\":\"https://docs.getcanonic.app/reference/error-codes\",\"name\":\"Error codes\",\"description\":\"The canonical error registry and its headless exit-code mapping.\",\"dateModified\":\"2026-10-19T11:43:39.663Z\",\"isPartOf\":{\"@id\":\"https://docs.getcanonic.app#website\"},\"breadcrumb\":{\"@id\":\"https://docs.getcanonic.app/reference/error-codes#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.getcanonic.app/reference/error-codes#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"canonic\",\"item\":\"https://docs.getcanonic.app\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Error codes\",\"item\":\"https://docs.getcanonic.app/reference/error-codes\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.getcanonic.app/reference/error-codes#article\",\"headline\":\"Error codes\",\"name\":\"Error codes\",\"description\":\"The canonical error registry and its headless exit-code mapping.\",\"url\":\"https://docs.getcanonic.app/reference/error-codes\",\"mainEntityOfPage\":{\"@id\":\"https://docs.getcanonic.app/reference/error-codes#webpage\"},\"image\":\"https://docs.getcanonic.app/og-image.png\",\"dateModified\":\"2026-10-19T11:43:39.663Z\",\"publisher\":{\"@id\":\"https://docs.getcanonic.app/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.getcanonic.app#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"canonic\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"canonic\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/reference/error-codes.md","siteName":"canonic","nav":{"global":null,"groups":[{"group":"Getting Started","pages":[{"title":"Introduction","href":"/introduction"},{"title":"Installation","href":"/installation"},{"title":"Quickstart","href":"/quickstart"},{"title":"End-to-end example","href":"/end-to-end-example"},{"title":"Configuring an LLM","href":"/configuring-an-llm"}]},{"group":"Concepts","pages":[{"title":"The three layers","href":"/concepts/three-layers"},{"title":"Semantics","href":"/concepts/semantics"},{"title":"Contracts \u0026 guardrails","href":"/concepts/contracts-and-guardrails"},{"title":"Tenancy \u0026 access control","href":"/concepts/tenancy-and-access-control"},{"title":"Knowledge","href":"/concepts/knowledge-layer"},{"title":"Connectors","href":"/concepts/connectors"},{"title":"Ingestion \u0026 reconciliation","href":"/concepts/ingestion-and-reconciliation"},{"title":"The semantic compiler","href":"/concepts/compiler"},{"title":"LLM \u0026 embeddings runtime","href":"/concepts/llm-runtime"},{"title":"Instrumentation \u0026 evaluation","href":"/concepts/instrumentation-and-eval"}]},{"group":"CLI Reference","pages":[{"title":"CLI Overview","href":"/cli-reference/overview"},{"title":"canonic connection","href":"/cli-reference/connection"},{"title":"canonic sl","href":"/cli-reference/sl"},{"title":"canonic mcp","href":"/cli-reference/mcp"},{"title":"canonic knowledge","href":"/cli-reference/knowledge"},{"title":"canonic pack","href":"/cli-reference/pack"},{"title":"canonic eval","href":"/cli-reference/eval"},{"title":"canonic setup","href":"/cli-reference/setup"},{"title":"canonic ingest","href":"/cli-reference/ingest"},{"title":"canonic review / apply","href":"/cli-reference/review-apply"},{"title":"canonic query / sql / assert","href":"/cli-reference/query-sql-assert"},{"title":"canonic decompose","href":"/cli-reference/decompose"},{"title":"canonic status / audit","href":"/cli-reference/status-report"},{"title":"canonic report","href":"/cli-reference/report"},{"title":"canonic completion","href":"/cli-reference/completion"}]},{"group":"MCP / Agent Integration","pages":[{"title":"Connecting your agent","href":"/mcp-integration/connecting-your-agent"},{"title":"MCP tools reference","href":"/mcp-integration/tools-reference"}]},{"group":"Guides","pages":[{"title":"Guide: ClickHouse","href":"/guides/clickhouse"},{"title":"Guide: Coffeehouse, canonic next to dbt (DuckDB)","href":"/guides/coffeehouse"},{"title":"Guide: Databricks","href":"/guides/databricks"},{"title":"Guide: Dutch Railway Network (DuckDB)","href":"/guides/dutch-railway"},{"title":"Guide: Ecommerce (Postgres)","href":"/guides/ecommerce"},{"title":"Guide: Jaffle Shop (dbt + MetricFlow)","href":"/guides/jaffle-shop"},{"title":"Guide: Marketplace (Tenant Scoping \u0026 RBAC)","href":"/guides/marketplace"},{"title":"Guide: Marketplace with Keycloak (OAuth 2.1)","href":"/guides/marketplace-keycloak"},{"title":"Guide: MySQL","href":"/guides/mysql"},{"title":"Guide: Apache Ossie Import (SQLite)","href":"/guides/ossie-retail"},{"title":"Guide: PostHog context pack (Docker demo)","href":"/guides/posthog-context-pack"},{"title":"Guide: Vehicle Rental (SQLite)","href":"/guides/rental"},{"title":"Guide: SaaS Analytics (all 8 binding kinds)","href":"/guides/saas-analytics"},{"title":"Guide: Snowflake","href":"/guides/snowflake"}]},{"group":"Compare","pages":[{"title":"canonic and other tools","href":"/compare/overview"},{"title":"canonic and dbt MetricFlow","href":"/compare/dbt-metricflow"},{"title":"canonic and Cube","href":"/compare/cube"},{"title":"canonic and LookML / Looker","href":"/compare/lookml-looker"},{"title":"canonic and Apache Ossie","href":"/compare/ossie-and-interchange"},{"title":"canonic and warehouse-native semantic layers","description":"How Snowflake semantic views and Databricks metric views relate to canonic, with short notes on Malloy, Rill, Omni and the Boring Semantic Layer.","href":"/compare/warehouse-native"}]},{"group":"Reference","pages":[{"title":"Error codes","href":"/reference/error-codes"},{"title":"canonic.yaml config schema","description":"Every top-level field in the project config file, and what it governs.","href":"/reference/config-schema"},{"title":"Semantic source schema","href":"/reference/semantic-schema"},{"title":"Contract schema","href":"/reference/contract-schema"},{"title":"Knowledge page schema","href":"/reference/knowledge-schema"},{"title":"Report schema","href":"/reference/report-schema"}]}]},"basePath":"","title":"Error codes - canonic","deploymentId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","buildId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","dynamics":[],"chunks":[]}