Skip to main content

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​

CodeMeansDo
SQL_SYNTAXthe text does not parse. Carries line and column.fix the SQL at that point
SQL_NOT_ALLOWEDa 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_QUERYthe 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​

CodeMeansDo
DOMAIN_REQUIREDno FROM <domain>name the domain
MULTIPLE_DOMAINStwo selects name different domains, or one domain under two namesone domain per statement, spelled one way
UNKNOWN_DOMAINFROM names no domain. Carries did_you_mean, or retired for a deleted one.use a suggested name
UNKNOWN_METRICMEASURE names no metric of the domain, or a qualified one (MEASURE(orders.revenue))use the bare name or a suggestion
UNKNOWN_FIELDno 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_DATASETthe qualifier names no dataset the domain exposesuse a suggestion
MEASURE_MISUSEMEASURE 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​

CodeMeansDo
AMBIGUOUS_REFERENCEtwo equally short routes reach that dataset. Carries routes.send one of the routes as written (Relationships)
UNKNOWN_RELATIONSHIPa path's link is not a to-one link of the dataset before ituse a suggestion, or check describe
INVALID_PATHa path that hops a to-many link, takes more than 8 hops, or is not a reference at allshorten or respell it
FIELD_NOT_REACHABLEno 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 axisgroup by a field every metric reaches, or ask the metrics in separate selects
DUPLICATE_DIMENSIONone field spelled two ways, along one route, in one selectkeep one spelling
NOT_GROUPEDa field or bucket read without being a GROUP BY keyadd it to GROUP BY, or use GROUP BY ALL
FILTER_NOT_PUSHABLEa WHERE condition that compares with an expression or another columncompute it over the results in a CTE
TYPE_MISMATCHa value, or a parameter, that does not fit the field's type or its own declarationfix the value (Filters)
VALUES_LIMITan IN list over 500 valuesmodel the list as a dataset
CROSS_CONNECTION_UNSUPPORTEDthe statement reads datasets on two connectionsone statement per connection

Time​

CodeMeansDo
TIME_FILTER_FORMa predicate on time that is not time >= a AND time < b at the top of WHERE, or a bound outside 1900 to 2200write the half-open window (Time)
GRAIN_NOT_SUPPORTEDa 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​

CodeMeansDo
NON_ADDITIVE_REAGGREGATIONSUM 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 sumsask for the metric at the coarser grouping, or the total in its own select
UNBOUND_PARAMETERthe SQL uses :name and the request gives no valuedeclare it in params
UNKNOWN_PARAMETERparams declares a name the SQL never usesremove it

Limits and cost​

CodeMeansDo
LIMIT_EXCEEDEDyour LIMIT is above the domain's or the platform's ceiling. Carries the effective maximum.lower it
RESULT_TOO_LARGEthe 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_EXPENSIVEthe 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_LONGtimeout_seconds above the maximumask for less
WAREHOUSE_TIMEOUT (504)the statement ran past its timeout and was cancellednarrow it, or ask for a longer timeout
CodeMeansDo
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 itresend with consent: {stale: true} or {warehouse: true}
CACHE_CANNOT_SERVEfrom_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_REJECTEDa cache-only metric (on_miss: reject) has no cube that can serve itchange the query to fit the cube
GRAIN_TOO_FINEa cache-only metric asked finer than its cube's grainask at the cube's grain or coarser

The model​

CodeMeansDo
BROKEN_DEFINITIONthe metric's stored definition points at something gone. Other metrics still answer.fix the metric (Names and changes)
AXIS_KIND_INVALIDthe metric's time axis is neither a moment nor a daydeclare a DateTimeTz or Date field and use it
SELECTION_NOT_CLOSEDthe domain does not select a dataset its metrics needadd it to select

Writing the model​

CodeMeans
VALIDATION_FAILEDa check of the write failed, such as an expression the warehouse refuses. The report says which.
SCHEMA_INVALIDthe document's shape is wrong: an unknown key, a bad timezone, resolution on a non-DateTimeTz field
CACHE_DIRECTIVE_REFUSEDa cache grain the metric cannot have: month, quarter or year, or finer than its axis
UNBOUND_SOURCEa table source that names no table in the connection's mirror
CROSS_CONNECTION_RELATIONSHIPa link between datasets on two connections
NAME_IMMUTABLEan update that changes a name. Use the rename action, or for a dataset, field or relationship, create anew.
NAME_TAKENthe name is held, as a current or a former name. Carries held_by.
REFERENCES_EXISTa delete of something still used. Lists what uses it.
FORMER_NAME_IN_USEreleasing a former name a cached metric's refresh still spells
STALE_WRITEbase_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​

CodeMeans
SQL_VENUE_REJECTEDthe 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_BUSYno 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.