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 jsonprints the error struct as JSON on stderr;validate --format jsonprints{issues, compile_errors, warnings}on stdout. Exit codes:0success,1engine-rejected (structured error),2usage error. Known asymmetries: load errors and non-validatevalidation issues are text-only. - REST & MCP — the identical body, wrapped:
{"error": {…}}. MCP tool failures return it as text content withisError: true; malformed MCP tool arguments return a plain-text schema error instead. - Python (
dosi_engine) —ModelError/QueryError/ExecuteError, all with.codeand.to_dict(); the planner'ssuggested_retryarrives ashint.
{"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.