Skip to content

Errors

Every surface — CLI, REST, MCP, Python — reports failures with the same structured errors. Error codes are the stable API; message text is not: match on code (snake_case), read candidates / suggested_retry / hint to self-correct, and never parse prose.

How errors are structured

Errors are staged along the pipeline, one code enum per stage:

Stage When it runs Payload shape
load reading the model file text only today (no code)
validate structural checks on the model {severity, code, location, message}
compile lowering the model to IR {code, location, message, candidates?, hint?}
plan compiling a metric query {code, message, metrics?, candidates?, suggested_retry?, condition?, missing_dimensions?}
execute running SQL on a warehouse {code, message, hint?}

Optional fields are omitted when empty, so payloads stay small. location says where to edit (metric 'revenue', relationships[2].to); candidates lists valid alternatives for a bad reference; suggested_retry / hint states the rewrite that would succeed; missing_dimensions lists the dataset.field items a query has to add to its group-by, the same items the metric catalog publishes as required_dimensions.

A JSON-path location starts at root datasets, relationships or metrics. Normal file loading upgrades historical single-model documents before validation; text validation accepts the flat format only. If a file cannot be safely rewritten, loading reports an error and preserves the source. See document shape.

Per surface:

  • CLI — --format json prints the error struct as JSON on stderr; validate --format json prints {issues, compile_errors, warnings} on stdout. Exit codes: 0 success, 1 engine-rejected (structured error), 2 usage error. Known asymmetries: load errors and non-validate validation issues are text-only.
  • REST & MCP — the identical body, wrapped: {"error": {…}}. MCP tool failures return it as text content with isError: true; malformed MCP tool arguments return a plain-text schema error instead.
  • Python (dosi_engine) — ModelError / QueryError / ExecuteError, all with .code and .to_dict(); the planner's suggested_retry arrives as hint.
{"error": {"code": "unknown_metric",
           "message": "unknown metric \"revenu\"",
           "metrics": ["revenu"],
           "candidates": ["revenue", "order_count", "..."]}}

Where each code can occur

Surface validate issues compile errors plan errors execute errors
CLI validate ✓ (issues) ✓ (compile_errors) — —
CLI query / explain / list ✓ (text, aborts) ✓ ✓ query --execute only
REST POST /v1/validate, MCP validate_model ✓ (in body) ✓ (in body) — —
REST /v1/query/compile · /explain, MCP compile_sql · explain_query — (model loads at startup) ✓ (lazy compile) ✓ —
REST /v1/query/execute, MCP run_query — ✓ ✓ ✓
Python Engine(...) ModelError("invalid_model") ModelError("compile_error") — —
Python compile_sql / query — — QueryError ExecuteError

Server-only codes (bad_request, unauthorized, forbidden, busy, internal, timeout) can accompany any REST/MCP call — see Server-level codes.

Model validation issues

Structural checks (dosi validate, POST /v1/validate). Errors make the model invalid; warnings don't — the model still compiles.

Code Severity When Fix
unsupported_version error version ≠ the Apache Ossie spec version this engine implements pin the version the message names
duplicate_name error two models, datasets, fields, metrics or relationships share a name rename one
empty_datasets error a semantic model has no datasets add at least one dataset
empty_columns error a relationship declares no column pairs fill from_columns / to_columns
column_count_mismatch error from_columns and to_columns differ in length they pair positionally — make them equal
unknown_dataset error a relationship endpoint names an undeclared dataset fix the from: / to: name
unknown_column error a relationship column is not a declared field of its dataset declare the field or fix the column
missing_sql_dialect error (metric) / warning (field) the expression has no SQL the engine can read provide portable SQL in expression.sql
self_relationship warning a relationship joins a dataset to itself usually intentional; review
relationship_target_not_unique warning to_columns is not the target's primary/unique key — the join may fan out point the join at a unique key, or, for a deliberate fact-to-fact pairing, declare cardinality: many_to_many
{"severity": "error", "code": "unknown_dataset",
 "location": "relationships[0].to",
 "message": "relationship \"orders_to_customers\" references unknown dataset \"customers\""}

Compile errors

Lowering a valid model to IR (compile_errors in the validate envelope; on query surfaces they surface when the model first compiles). All carry location; candidates / hint where noted.

Code When Payload extras
invalid_metric_reference an AGG argument does not name a dataset metric, or its argument has an invalid shape write AGG(dataset.metric) in the model-level expression
unparseable_expression expression is not parseable SQL
no_sql_dialect the selected mode has no usable SQL for the field or metric provide portable SQL in expression.sql
unknown_dataset SUM(no_such.amount) — qualifier is not a dataset candidates: dataset names
unknown_field dataset.field where the dataset lacks that field candidates: that dataset's fields
unknown_column bare column found in no dataset hint: qualify as dataset.field
ambiguous_column bare column exists in several datasets candidates: qualified spellings
not_an_aggregate metric expression doesn't aggregate hint: wrap in SUM(...)
nested_aggregate SUM(MAX(...))
bare_column_in_metric non-aggregated column (or literal-only aggregate) in a metric hint: aggregate a dataset field
cross_dataset_aggregate one aggregate mixes columns of two datasets split the aggregate
count_star_needs_dataset bare COUNT(*) in a multi-dataset model hint: count a key column
unsupported_aggregate aggregate outside SUM/COUNT/COUNT DISTINCT/AVG/MIN/MAX
multi_column_count_distinct declared but currently never produced
window_in_metric window function in a metric expression hint: precompute in the dataset
subquery_in_metric subquery in a metric expression
measure_name_collision an explicit (D-MEASURE) measure name clashes: one aggregate with two explicit names, or one name on two aggregates (generated names that coincide are told apart by a signature tag instead) hint on some sites
metric_reference_cycle D-DERIVE compose metrics reference each other message shows the cycle path
field_reference_cycle fields that read a D-LOD value reference each other message shows the cycle path
derive_expression_mismatch authored fallback expression ≠ the derive expansion hint
invalid_datus_extension malformed DATUS payload (bad v, unknown field ref, …) hint with a docs anchor
unsupported_datus_ext_version payload v has a newer major / pre-1.0 hint names the supported major
datus_ext_key_required requires: [...] names a key this engine doesn't implement
not_implemented a declared shape outside the current derive/window/LOD scope hint with a docs anchor

A query that uses an invalid metric, directly or through another metric, returns the original compile error code. The optional ossie_code gives the corresponding Ossie diagnostic for a field outside an aggregate (E_UNAGGREGATED_FINER_GRAIN_REFERENCE), a windowed metric expression (E_DEFERRED_WINDOWED_METRIC), or an aggregate with ambiguous dataset ownership (E_AMBIGUOUS_MEASURE_GRAIN). dosi validate checks every metric.

Compile warnings

Non-fatal: the model compiled, but not everything took effect. Shape {code, location, message}; CLI prints ! … on stderr and exits 0.

Code When
ignored_vendor_extension basic mode ignored a DATUS extension, or a dataset-scoped metric was evaluated from its Ossie expression in either mode
datus_ext_version_ahead payload declares a newer minor; unknown keys were dropped (named in the message)
datus_ext_key_newer_than_declared a key newer than the declared v was honored anyway
datus_ext_requires_missing a non-null silent-impact key (time, measure) is missing from requires; add it to protect older consumers
compose_no_conformed_dimensions a compose metric's members share no dimension — no query can group it
datus_time_format_misplaced a top-level format on a time dimension holds a storage layout (%Y%m%d, …); it is presentation metadata and was ignored — the layout belongs in the time block (D-FORMAT)
datus_param_unbounded a D-PARAM int/float parameter declares no allowed/min/max
datus_param_unused a declared parameter no slot references
underdeclared_field (datus mode, dosi validate only) a field with no is_dimension that looks like a measurement, a business key, or an unmarked time column, and is therefore offered as a grouping dimension
dimension_role_conflict (datus mode, dosi validate only) a field declared is_dimension: true that a metric aggregates as a measure; the declaration is honored and the message names the metric
datus_param_opaque_token allowed values the ASCII stem sanitizer cannot tell apart; their columns take an h<hex> suffix (the message names the mapping)
aggregate_field_dropped a field's expression aggregates but declares no D-LOD grain — the field is dropped, and references to it fail with unknown_field
field_dropped_needs_params a field's expression has :name holes no params declaration on the field fills (none declared, or basic mode) — the field is dropped, and references to it fail with unknown_field

Query planning errors

Rejections of a query on either plane — metric (dosi query, /v1/query/*, compile_sql / run_query) or detail (dosi select, /v1/select/*, compile_select / select). All HTTP 400 except not_implemented → 501 and internal → 500.

Code When Payload extras
empty_query no metrics requested candidates: all metrics
dimensions_required a request to the deprecated attribute named no dimensions; the engine does not guess which columns explain a change. The two attribution tools refuse the same request with their own request errors metrics, candidates: what the metric is worth decomposing over, best first, suggested_retry: a dimensions fragment
unknown_metric metric name not in the model metrics, candidates
unknown_dimension group-by item not a dimension — including a metric name, whose retry says how to request it instead candidates or suggested_retry
ambiguous_dimension bare field exists in several datasets candidates: qualified spellings
grain_on_non_time_dimension :grain on a non-time field suggested_retry
grain_too_fine requested grain finer than the stored time_granularity, a time-range bound falling inside a period a time.format column cannot subdivide, or a bound a window query widens falling inside a bucket of its grain (window) suggested_retry: the bound that keeps the partial period and the one that drops it
duplicate_output_name two group-by items — or two metric columns — produce one output column suggested_retry
unknown_order_key order key is neither a metric nor a group-by item; also a metric name under a list binding, which expands to several columns candidates: the accepted keys, or the bindings + suggested_retry
unsupported_filter subquery/window in where, a D-FORMAT encoded field in where_sql, a bare metric name under time_ranges (name {metric}__{tag}), or a malformed time range candidates: the tagged names, when relevant. Use time_range for encoded time fields.
aggregate_in_where inline aggregate in where suggested_retry: declare the metric, select it, and name it in where_sql (filters)
result_filter_metric_not_selected where_sql names a model metric the query does not select; a metric condition filters the query's own result rows metrics, candidates: the selected metrics, suggested_retry
result_filter_unprojected one where_sql conjunct names a metric and a field the query does not group by — no position can evaluate both suggested_retry: group by the field, or split the conjunct
no_join_path no dataset reaches the measure and all group-bys many→one, whatever the aggregate — including two facts no relationship connects, and a dimension on a column only one of two paired facts reaches (a where_sql condition there that another part of the query reads is where_needs_context instead) metrics, suggested_retry: the D-CONFORM pairing when that is why, else the reachable dimensions or the relationship to declare
ambiguous_join_path more than one relationship path — semantics would differ candidates: the paths, suggested_retry
fan_out_risk duplicate-sensitive aggregate across a fanning join: some dataset reaches both the measure and the group-bys, so a duplicate-insensitive aggregate would evaluate metrics, suggested_retry
time_range_needs_dimension several time dimensions in scope; range target unclear candidates
no_primary_time_dimension metric_time grouped on a metric with no primary time dimension, a time range no part of the query has a time field for, or a window over facts whose dates are not paired candidates, suggested_retry (for the window: pair the dates with D-CONFORM)
time_axis_ambiguous a part of the query reads a dataset with several time fields and no time_dimension, so the period has no column to land on candidates: the time fields, suggested_retry
context_unreadable a context_filter condition names columns no part of the query can read — it would scope nothing candidates: the datasets the query reads, suggested_retry
where_needs_context a where_sql row condition some parts of the query cannot read while others can — a column of a table only a fixed field reads, or of one fact among several. where_sql applies to every metric's rows, so it cannot stand; context_filter applies it to each part that reads it metrics: the metric that cannot read it, condition, suggested_retry: the parts that can read it
metric_time_conflict no longer raised: metrics on one base with different time axes now plan one branch per axis (semantics); the code stays for wire compatibility
unconformed_dimension dimension outside a derived metric's conformed set metrics, candidates, suggested_retry
unknown_metric_param params names a parameter that neither a queried metric nor a level-of-detail field the query reads declares candidates: declared names, suggested_retry
param_out_of_domain binding outside the parameter's type/domain, an empty or repeated list, a list where one value is required (attribution), an empty or oversized set, or a name declared as a set on one metric and as one value on another metrics, suggested_retry: a valid params fragment
param_expansion_too_large list bindings expand to more than 64 output columns metrics, suggested_retry
unknown_query_key the query carries a key its type does not define — usually a misspelling, refused rather than silently dropped candidates: the keys the query defines, suggested_retry
window_reset_too_fine window resets finer than the queried grain suggested_retry
window_offset_misaligned a window offset does not land on a bucket of the queried grain (1 month over quarters or weeks), so every row would read NULL metrics, suggested_retry: the grains it lands on
window_exclude_not_grouped a window's partition.exclude names a dim the query does not group by, anywhere in the dependency chain metrics: the requested metrics whose chain is short a dim (the message names the levels), candidates: the query's dims, missing_dimensions and suggested_retry: all the dims to add, at once
lod_dimension_not_grouped a level-of-detail metric names a dim the query does not group by: one a keyed exclude removes (it would remove nothing), or a key of a keyed fixed metric, which has to be grouped without a time grain. A compose over such a metric counts metrics: the requested metrics (the message names the declarations), missing_dimensions and suggested_retry: all the dims to add, at once
time_axis_not_grouped a window orders, resets or partitions by time, anywhere in the dependency chain, and the group-by lacks its time axis at a grain candidates: the axis field and metric_time, missing_dimensions: the axis, suggested_retry: the item to add with a grain
dialect_unsupported_window_function target dialect lacks the needed window function metrics, suggested_retry
unknown_dataset a detail query's from names no dataset candidates: dataset names
unknown_subtype <Concept> is <Name> in a filter names no derived subtype of that concept, or one the current mode left unmapped candidates: the concept's derived subtypes, suggested_retry
detail_fanout a detail query reached a dataset only against the join direction; one root row would become several candidates: the reverse path, suggested_retry: the root to use instead
metric_in_detail_query a metric appeared in a detail projection metrics, suggested_retry: the dosi query call
unknown_relationship a relationship-prefixed reference names no relationship candidates: edges leaving the dataset reached so far, suggested_retry
invalid_relationship_path a named path does not chain, revisits a dataset, or does not leave the query's base candidates: edges leaving that dataset, suggested_retry
not_implemented legal per the model, outside current engine scope — including a query that reaches one dataset by two paths, and an unsupported LOD combination, such as a window metric alongside LOD or incompatible reaggregation grains metrics or candidates, suggested_retry
internal engine invariant violation — retrying won't help; report a bug

Query warnings

A query that compiles may still not mean what it says. Its result carries warnings (S-FILTER-5); each has a code, a level, a message, and when they apply the part it concerns, the condition it is about and a hint saying how to change the query. warning means the result may not answer the question asked; info records how a condition landed.

Code Level When
context_skipped info; warning for a fixed rollup whose dataset has columns of the same names — hint spells the condition on them a part cannot read a context_filter condition (or a time range pinned to a column it cannot read), so the condition does not scope it
time_axis_missing warning a part's dataset has no time field, so the period does not scope it
empty_time_window warning a fixed rollup's period and a context_filter condition on the same column leave no day
where_not_in_lod warning a where_sql row condition filters the rows the metrics aggregate but not a fixed field the query reads, though that field's rollup could read the condition and the condition is not only on its keys. Not raised for a condition on the column the field's base already windows with its own parameters
param_window_cut warning the query binds the window a fixed field's base declares with parameters, and the period or a context_filter date condition on the same column leaves part of it out. When a context_filter condition cuts it, condition names that condition and the hint is about it, not time_range
lookback_cut warning; info for a running or trailing frame without a reset a previous-period or running window looks back along its time axis, and a where_sql or context_filter condition on that axis removes the rows it looks back to. A period in time_range widens the scan for an offset and for a frame back to its reset; a frame without a reset reads only the periods the query keeps wherever the date is written, so for it this only says where it starts
display_only info in a window query, a where_sql condition on a dimension the window compares across only picks the rows shown; the ranks and shares are still computed over every value

Both positions of a condition are legitimate and answer different questions, so none of these refuses the query: in a ranking, where asks for the rank among all values and context_filter for the rank among the kept ones; for a fixed field, where keeps the value over all rows and context_filter computes it over the kept ones.

A typical self-correction loop: unknown_metric → pick from candidates → retry; fan_out_risk → follow suggested_retry (group by reachable dimensions, or restate with COUNT DISTINCT/MIN/MAX):

{"code": "fan_out_risk",
 "message": "metric \"store_productivity\" aggregates Sum over dataset \"store\", which has no many→one path to [\"item\"]; evaluating a duplicate-sensitive aggregate (SUM/AVG/COUNT) across that join would double-count rows",
 "metrics": ["store_productivity"],
 "suggested_retry": "group by dimensions reachable from the metric's dataset, or restate the metric with a duplicate-insensitive aggregate (COUNT DISTINCT/MIN/MAX)"}

The detail plane's two loops work the same way. detail_fanout hands back the root that answers the question at the right grain, and ambiguous_join_path hands back the relationship prefixes that name each candidate path — both ready to paste into the next call. See Query detail rows.

Execution errors

Running compiled SQL on a warehouse (query --execute, /v1/query/execute, run_query). Shape {code, message, hint?}.

Code HTTP When
config 400 connection profile broken (bad URI, unopenable DuckDB file, missing driver option)
connection 502 warehouse unreachable
auth 502 credentials rejected
sql_rejected 502 the warehouse rejected the SQL (missing table, type error) — message embeds the warehouse's own error
driver 502 driver-level failure after connecting
timeout 504 statement or server execute timeout

Server-level codes

dosi-server adds transport-level codes in the same envelope, {"error": {"code", "message"}}:

Code HTTP When
bad_request 400 malformed JSON body, unknown dialect
unauthorized 401 missing/wrong bearer token
forbidden 403 execute called with --disable-execute
busy 429 all execution slots taken (Retry-After: 1)
timeout 504 the server's own execute timeout
internal 500 unexpected server failure

Python exceptions

The dosi_engine wheel raises one exception hierarchy (OsiError base, .code + .to_dict() on all):

Exception Codes Notes
ModelError io, parse, ontology, invalid_model, compile_error invalid_model carries issues; compile_error carries compile_errors plus the first error's candidates/hint; ontology (an ontology that could not be parsed or lowered) lists every refusal with its own code in the message
QueryError every plan code above, and the attribution tools' request errors suggested_retry arrives as hint; condition and missing_dimensions are attributes; an attribution request error has detail["field_path"]
ExecuteError every execute code above

Compile warnings are raised as Python RuntimeWarnings at Engine(...) construction — python -W error promotes them to failures.

SQL-generation errors (parse_error, unsupported_aggregate, …) are an internal boundary between planner and renderer; they surface inside compile or plan errors above, never as a user-level contract of their own.

Every code on this page is pinned by tests: a catalog of negative cases runs on every commit and checks each code's actual payload.