Error codes

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.

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:

canonic query --metrics rental_revenue --dimensions customers.country

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:

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

Getting Started

Concepts

CLI Reference

MCP / Agent Integration

Guides

Reference

Resolving `ambiguous`

Resolving `tenant_unresolved`

Resolving `tenant_scope_missing`

Resolving `tenant_forbidden`

Errors without a registry code

​Resolving ambiguous

​Resolving tenant_unresolved

​Resolving tenant_scope_missing

​Resolving tenant_forbidden

​Errors without a registry code

Resolving `ambiguous`

Resolving `tenant_unresolved`

Resolving `tenant_scope_missing`

Resolving `tenant_forbidden`

Errors without a registry code