Errors
Synced from semantic-layer
Source: docs/guide/14-errors.md at origin/main (3688d236), synced 2026-11-05. Do not edit this page here; change the source and run yarn sync:semantic.
Every refusal has a stable code, a message that says what to write instead, and details such as
the field, did_you_mean or a maximum. A query error is a 422 that you fix by rewriting. In plan
mode it comes back inline, as valid: false with errors. The codes below are grouped by the step
that raises them.
Reading the statement
| Code | Means | Do |
|---|---|---|
SQL_SYNTAX | the text does not parse. Carries line and column. | fix the SQL at that point |
SQL_NOT_ALLOWED | a construct the language does not admit, or a cap: over 20,000 characters, not exactly one statement, more than 8 semantic selects, nesting too deep. Carries construct. | use the alternative the message names (Composing queries) |
INVALID_QUERY | the request envelope is wrong: a missing sql, an unknown key, a bad params declaration, a timezone that is not a place, a malformed draft. Carries field. | fix the named member |
Names
| Code | Means | Do |
|---|---|---|
DOMAIN_REQUIRED | no FROM <domain> | name the domain |
MULTIPLE_DOMAINS | two selects name different domains, or one domain under two names | one domain per statement, spelled one way |
UNKNOWN_DOMAIN | FROM names no domain. Carries did_you_mean, or retired for a deleted one. | use a suggested name |
UNKNOWN_METRIC | MEASURE names no metric of the domain, or a qualified one (MEASURE(orders.revenue)) | use the bare name or a suggestion |
UNKNOWN_FIELD | no such field in this domain (it may exist but not be exposed), or an unqualified one. Carries did_you_mean. | write dataset.field, or use a field the domain exposes |
UNKNOWN_DATASET | the qualifier names no dataset the domain exposes | use a suggestion |
MEASURE_MISUSE | MEASURE used wrongly: in WHERE or GROUP BY, outside a semantic select, around anything but one metric name. Also a bare metric name used as a field, or SUM(field) in a semantic select. | MEASURE(metric) in the select list. Filter it in HAVING. |
Fields and paths
| Code | Means | Do |
|---|---|---|
AMBIGUOUS_REFERENCE | two equally short routes reach that dataset. Carries routes. | send one of the routes as written (Relationships) |
UNKNOWN_RELATIONSHIP | a path's link is not a to-one link of the dataset before it | use a suggestion, or check describe |
INVALID_PATH | a path that hops a to-many link, takes more than 8 hops, or is not a reference at all | shorten or respell it |
FIELD_NOT_REACHABLE | no route from a metric's anchor reaches the field through the links the domain exposes, or a path does not start at the anchor, or a window bounds a metric with no time axis | group by a field every metric reaches, or ask the metrics in separate selects |
DUPLICATE_DIMENSION | one field spelled two ways, along one route, in one select | keep one spelling |
NOT_GROUPED | a field or bucket read without being a GROUP BY key | add it to GROUP BY, or use GROUP BY ALL |
FILTER_NOT_PUSHABLE | a WHERE condition that compares with an expression or another column | compute it over the results in a CTE |
TYPE_MISMATCH | a value, or a parameter, that does not fit the field's type or its own declaration | fix the value (Filters) |
VALUES_LIMIT | an IN list over 500 values | model the list as a dataset |
CROSS_CONNECTION_UNSUPPORTED | the statement reads datasets on two connections | one statement per connection |
Time
| Code | Means | Do |
|---|---|---|
TIME_FILTER_FORM | a predicate on time that is not time >= a AND time < b at the top of WHERE, or a bound outside 1900 to 2200 | write the half-open window (Time) |
GRAIN_NOT_SUPPORTED | a bucket off the grain ladder, bare time without a bucket, or a grain finer than the axis offers. Carries supported. | use a listed grain |
Composition and parameters
| Code | Means | Do |
|---|---|---|
NON_ADDITIVE_REAGGREGATION | SUM or AVG, window sums included, over a column whose metric's rollup is not sum: a ratio, an average, a distinct count, a median, a percentile, or a derived metric that adds two sums | ask for the metric at the coarser grouping, or the total in its own select |
UNBOUND_PARAMETER | the SQL uses :name and the request gives no value | declare it in params |
UNKNOWN_PARAMETER | params declares a name the SQL never uses | remove it |
Limits and cost
| Code | Means | Do |
|---|---|---|
LIMIT_EXCEEDED | your LIMIT is above the domain's or the platform's ceiling. Carries the effective maximum. | lower it |
RESULT_TOO_LARGE | the answer has more rows than a ceiling you did not write. No rows are returned. | narrow the window or filters, group coarser, or add ORDER BY … LIMIT n |
QUERY_TOO_EXPENSIVE | the warehouse would scan or bill more than the byte cap. Consent does not lift it. | narrow the window or filters, or use a metric a cube serves |
TIMEOUT_TOO_LONG | timeout_seconds above the maximum | ask for less |
WAREHOUSE_TIMEOUT (504) | the statement ran past its timeout and was cancelled | narrow it, or ask for a longer timeout |
Cache and consent
| Code | Means | Do |
|---|---|---|
CACHE_MISS_CONSENT_REQUIRED (409) | running on the metered warehouse needs your yes. Carries the plan and price. | resend with consent: {warehouse: true} |
STALE_CACHE_CONSENT_REQUIRED (409) | the cube is stale and the metric asks before serving it | resend with consent: {stale: true} or {warehouse: true} |
CACHE_CANNOT_SERVE | from_cache was set and a cube cannot serve every metric. Carries every reason. | drop from_cache, or change the query to fit the cube |
CACHE_MISS_REJECTED | a cache-only metric (on_miss: reject) has no cube that can serve it | change the query to fit the cube |
GRAIN_TOO_FINE | a cache-only metric asked finer than its cube's grain | ask at the cube's grain or coarser |
The model
| Code | Means | Do |
|---|---|---|
BROKEN_DEFINITION | the metric's stored definition points at something gone. Other metrics still answer. | fix the metric (Names and changes) |
AXIS_KIND_INVALID | the metric's time axis is neither a moment nor a day | declare a DateTimeTz or Date field and use it |
SELECTION_NOT_CLOSED | the domain does not select a dataset its metrics need | add it to select |
Writing the model
| Code | Means |
|---|---|
VALIDATION_FAILED | a check of the write failed, such as an expression the warehouse refuses. The report says which. |
SCHEMA_INVALID | the document's shape is wrong: an unknown key, a bad timezone, resolution on a non-DateTimeTz field |
CACHE_DIRECTIVE_REFUSED | a cache grain the metric cannot have: month, quarter or year, or finer than its axis |
UNBOUND_SOURCE | a table source that names no table in the connection's mirror |
CROSS_CONNECTION_RELATIONSHIP | a link between datasets on two connections |
NAME_IMMUTABLE | an update that changes a name. Use the rename action, or for a dataset, field or relationship, create anew. |
NAME_TAKEN | the name is held, as a current or a former name. Carries held_by. |
REFERENCES_EXIST | a delete of something still used. Lists what uses it. |
FORMER_NAME_IN_USE | releasing a former name a cached metric's refresh still spells |
STALE_WRITE | base_rev is older than a change to what the write touches |
WRITE_CONFLICT (409) | another write landed between this one's check and its apply. Send it again. |
The venue
| Code | Means |
|---|---|
SQL_VENUE_REJECTED | the warehouse or the cache refused the composed statement, for example over a column your outer SQL names. Carries the venue's first line. |
WAREHOUSE_EXECUTION_FAILED (502) | the warehouse failed to run it: a dropped connection, a missing grant |
WAREHOUSE_QUOTA_EXCEEDED (429) | the warehouse account's own quota. Retry later. |
WAREHOUSE_BUSY | no warehouse session was free. Retry. |
CACHE_EXECUTION_FAILED (502) | the cube worker failed to run it. It is not retried on the warehouse. |
CATALOG_UNAVAILABLE (503) | the model could not be read. Retry. |