Dataface Error Reference¶
Auto-generated from dataface.core.diagnostics.REGISTRY. Every ERR-* code Dataface can raise, grouped by docs topic.
charts¶
ERR-AREA-ENCODING-SWAPPED — Area chart x/y encoding looks swapped¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Chart {chart_id!r} (area): {reason} Area charts always plot x as the dimension and y as the value — there is no orientation knob to rotate an area chart, so a swapped x/y silently bakes a broken axis.
Fired when an area chart's encoding looks incorrect: either y is non-numeric (should be the measure), or x is a numeric measure with stack enabled. Area charts always plot x as the dimension and y as the value — there is no orientation knob.
ERR-AREA-STACKED-LOG-SCALE-NOT-SUPPORTED — Stacked area and log scale are incompatible¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Chart {chart_id!r} (area): `style.stack: {stack}` with axis_y.scale.type: log is not supported — a stacked band's top encodes a cumulative sum, which a log scale can't represent (the baked domain would be computed from unstacked values and clip the real stacked extent). Use `stack: none`, or drop the log scale.
Fired when a stacked area chart (style.stack: zero/normalize/center) is combined with axis_y.scale.type: log. A cumulative stack top is meaningless on a log scale. Use stack: none, or drop the log scale.
ERR-BAR-DUPLICATE-ROWS — Bar chart data has duplicate rows that require aggregation¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
{chart_type} chart {chart_id!r} requires pre-aggregated data with at most one row per plotted key ({field_list}). Found duplicate rows for {duplicate_preview}. Aggregate in the query before rendering.
Fired when a bar, horizontal-bar, or grouped-bar chart receives data with more than one row per plotted key. These chart types require pre-aggregated data; aggregate in the query before rendering.
ERR-BAR-LOG-SCALE-NOT-SUPPORTED — Log scale is not supported on bar charts¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Chart {chart_id!r} (bar): axis_y.scale.type: log is not supported — a bar's length encodes magnitude from zero, which a log scale makes meaningless. Use line or area, or drop the log scale.
Fired when a bar chart's y axis is set to scale.type: log. A bar's length encodes magnitude from zero, which a log scale makes meaningless. Use a line or area chart, or drop the log scale.
ERR-BAR-Y-NOT-NUMERIC — Bar chart y column is not numeric¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Chart {chart_id!r} (bar): y column {y_field!r} is not numeric. Bar charts always plot x as the category and y as the measure, regardless of orientation — use a numeric column for y.
Fired when a bar chart's y: column contains non-numeric data. Bar charts always use y as the measure axis regardless of orientation — use a numeric column for y.
ERR-COLOR-NULL-SERIES — Color column contains NULL values¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
{chart_type} chart {chart_id!r} has {null_rows} row(s) with a NULL value in its color column {color_field!r}. A NULL category cannot be painted or named in the legend, but its rows still occupy stack space — the chart would read as bars floating off the baseline. Give every row a category in the query (e.g. COALESCE({color_field}, 'Unknown')).
Fired when the column bound to a chart's color channel contains NULL values. The renderer cannot assign a NULL a palette slot or a legend entry, so the series would consume stack space while being invisible and unattributable. Fix the grain in the query — the most common cause is a CASE with no ELSE, or an ELSE that passes the raw column through unchanged.
ERR-CONCAT-OVERSHOOT-NONPOSITIVE — Overshoot correction produced a non-positive pane width¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Overshoot correction produced a non-positive pane width ({new_w:.1f}px): pane width {orig_w:.1f}px minus overshoot {overshoot:.1f}px. The chart content (title, subtitle, axis labels, or legend) is wider than the available canvas ({target_width:.1f}px).
Fired when the overshoot correction algorithm for a concatenated layout produces a non-positive pane width. The chart content (title, subtitle, axis labels, or legend) is wider than the available canvas.
ERR-FORMAT-INVALID — Format spec is not a known alias or a valid d3-format spec¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Unknown number format {spec!r} at {field_path}. It is not a defined format alias and is not a valid d3-format spec ({reason} at position {position}).
Fired when an authored format: string is not a defined theme/face format alias, not one of Dataface's native (non-d3) formatter keys, and fails to parse as a d3-format spec. Check for typos against the theme's formats: alias table, or use a valid d3-format spec (https://d3js.org/d3-format).
ERR-HISTOGRAM-NON-NUMERIC — Histogram x field is not numeric¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Histogram chart {chart_id!r} requires a numeric x field for binning, but {field!r} is {vl_type!r}. Use a quantitative (numeric) column as x.
Fired when a histogram chart's x field is not numeric (quantitative). Histograms bin values into ranges, which requires a numeric column. Use a quantitative column as x.
ERR-INPUT-INVALID — Invalid render input¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Fired when the render layer receives input data that fails a structural check. The message carries the specific validation error.
ERR-KPI-MULTIROW — KPI query returned more than one row¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
KPI chart {chart_id!r} expects exactly 1 row, got {row_count}. Use a query that returns a single row (e.g. SELECT SUM(...) or LIMIT 1).
Fired when a KPI chart's query returns more than one row. KPI charts display exactly one value; use a query that returns a single row (e.g. SELECT SUM(...) or LIMIT 1).
ERR-LABEL-VALUES-INVALID-DATE — label.values entry is not a valid ISO date¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
style.axis_x.label.values entries must be ISO date or datetime strings (e.g. '2024-01-01') or date/datetime objects; got {value!r}.
Fired when an entry in style.axis_x.label.values cannot be parsed as an ISO date or datetime. Use ISO date strings (e.g. '2024-01-01') or date/datetime objects.
ERR-LABEL-VALUES-MEASURE-AXIS — label.values is not supported on the measure axis¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
style.axis_y.label.values is not supported — the measure axis (axis_y) is never temporal in Dataface's cartesian model. label.values only applies to a temporal axis_x; remove it from axis_y.
Fired when style.axis_y.label.values is set. The measure axis (axis_y) is never temporal in Dataface's cartesian model; label.values only applies to a temporal axis_x. Remove it from axis_y.
ERR-LABEL-VALUES-NOT-TEMPORAL — label.values requires a temporal x-axis¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Fired when style.axis_x.label.values is set on an x-axis that can't honor it — either the x-axis values aren't valid ISO dates or datetime objects, or the chart's horizontal-bar categorical axis never applies label filtering regardless of date format.
ERR-LABELS-FIELD-NOT-FOUND — labels.field names a column not in the query result¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Fired when labels.field names a column that is not present in the query result. Check the column name against the actual columns returned by the query.
ERR-LAYERS-AMBIGUOUS-Y-DOMAIN — Chart-level y domain is ambiguous with independent layer scales¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Chart {chart_id!r} sets axis_y.scale.domain={domain!r} but the layers use independent y scales (left and right sides differ). A chart-level domain is ambiguous when each side has its own scale — set axis_y.scale.domain on the individual layer instead.
Fired when a chart sets axis_y.scale.domain at the chart level but the layers use independent (split) y scales. A chart-level domain is ambiguous when left and right sides have different scales. Set axis_y.scale.domain on the individual layer instead.
ERR-LINE-Y-NOT-NUMERIC — Line chart y column is not numeric¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Chart {chart_id!r} (line): y column {y_field!r} is not numeric. Line charts always plot x as the dimension and y as the value — use a numeric column for y.
Fired when a line chart's y: column contains non-numeric data. Line charts always use y as the value axis — use a numeric column for y.
ERR-LOG-SCALE-REQUIRES-POSITIVE-DATA — Log scale requires strictly positive data¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Chart {chart_id!r}: column {y_field!r} has a value <= 0, but axis_y.scale.type: log requires strictly positive data — a log domain is undefined at and below zero. Filter out the non-positive rows, or drop the log scale.
Fired when axis_y.scale.type: log is used but the y column contains a value ≤ 0. A log domain is undefined at and below zero. Filter out the non-positive rows, or drop the log scale.
ERR-MAP-LOOKUP-KEY-MISMATCH — Map chart cannot join on mismatched key format¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Map chart {chart_id!r} cannot join lookup field {lookup_field!r} to geo source {geo_source!r} on key {geo_key!r}: the geo source expects {expected_format} keys like {expected_samples}, but the query returned values like {query_samples}.
Fired when a map chart's lookup field values do not match the format expected by the geo source. Check that the lookup field uses the same key format (e.g. FIPS codes, ISO country codes) as the geo source.
ERR-PERCENT-RANGE — Percent format received a 0-100-shaped value instead of a ratio¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Value {value!r} passed to percent format {format_spec!r} looks 0-100-shaped, but percent formats expect a 0-1 ratio (0.182, not 18.2). To fix: divide by 100 in SQL so the value is a ratio, or switch to the `percent_number`/`percent_number_delta` formats if the value is already in the 0-100 scale (e.g. 18.2 means 18.2%).
Fired when a percent format receives a value that looks like it is already in the 0-100 scale rather than the 0-1 ratio scale that percent formats expect. Divide by 100 in SQL so the value is a ratio, or switch to a percent_number format.
ERR-RESOLVED-PIE-DATA-MISMATCH — Resolved pie rows do not match its recording¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Resolved pie {chart_id!r} was finalized from different query rows. Resolve the chart and record its data in the same emission.
Fired when replay data differs from the rows used to finalize pie label and attached-table policy. Resolved board artifacts and recordings must come from the same emission.
ERR-RESOLVED-PIE-WIDTH-MISMATCH — Resolved pie width does not match its render slot¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Resolved pie {chart_id!r} was finalized at width {resolved_width}, not {render_width}. Resolve the chart again for the target slot.
Fired when a resolved pie is rendered at a different width from the one used to finalize its label and attached-table layout. Resolve the chart again with the actual target width before rendering.
ERR-SCALE-DOMAIN-REQUIRES-CONTINUOUS-X — axis_x.scale.domain requires a continuous x-axis scale¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Chart {chart_id!r}: axis_x.scale.domain is set, but the x-axis resolved to a {vl_type!r} (categorical) scale, not a continuous one. An explicit [low, high] domain only extends a continuous scale — on a categorical scale Vega-Lite reads it as exactly two category values, collapsing every mark onto the first one. If the x field is a date, add `axis_x.scale.type: temporal` to force a continuous temporal scale.
Fired when axis_x.scale.domain is set but the x-axis resolves to a categorical (ordinal/nominal) scale rather than a continuous one. An explicit [low, high] domain only extends a continuous scale; on a categorical scale Vega-Lite reads it as exactly two category values. Add axis_x.scale.type: temporal to force a continuous temporal scale if needed.
ERR-TICKS-COUNT-REQUIRES-NON-LOG-SCALE — ticks.count is not supported with log scale¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Chart {chart_id!r}: axis_y.ticks.count is not supported with scale.type: log — a target tick count on a log axis is nonsense; Vega-Lite computes log-decade ticks natively. Remove ticks.count.
Fired when axis_y.ticks.count is combined with axis_y.scale.type: log. A target tick count on a log axis is meaningless because Vega-Lite computes log-decade ticks natively. Remove ticks.count.
ERR-TICKS-INTERVAL-MEASURE-AXIS — ticks.interval is not supported on the measure axis¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
style.axis_y.ticks.interval/step is not supported — the measure axis (axis_y) is never temporal in Dataface's cartesian model. ticks.interval/step only apply to a temporal axis_x; remove them from axis_y.
Fired when style.axis_y.ticks.interval or step is set. The measure axis (axis_y) is never temporal in Dataface's cartesian model; ticks.interval/step only apply to a temporal axis_x. Remove them from axis_y.
ERR-TICKS-INTERVAL-NOT-TEMPORAL — ticks.interval requires a continuous temporal x-axis¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
style.axis_x.ticks.interval requires a continuous temporal x-axis, but {field!r} resolved to a {vl_type!r} scale. Force a continuous scale with axis_x.type: temporal (or axis_x.time_unit: none), or remove ticks.interval.
Fired when style.axis_x.ticks.interval is set but the x-axis does not resolve to a continuous temporal scale. Force a continuous scale with axis_x.type: temporal (or axis_x.time_unit: none), or remove ticks.interval.
ERR-VEGA-LITE-UNSUPPORTED-TYPE — Chart type does not render to a Vega-Lite spec¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Fired when a chart type is asked to render a Vega-Lite spec but does not support that output format. Use a Vega-Lite-compatible chart type or choose a different output format.
errors¶
ERR-BOARD-ARTIFACT-INVALID — Resolved-board artifact does not match the expected schema¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Board artifact is invalid: {detail}. It may have been produced by an incompatible dft version, hand-edited, or truncated. Re-emit it with `dft board emit`.
Fired when a resolved-board artifact fails to validate against ResolvedFace while loading it for replay. The artifact is the published, versioned contract a resolved board serializes to — this means the file is not a valid instance of that contract.
ERR-BOARD-RECORDING-INVALID — Board recording sidecar does not match the expected schema¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Board recording is invalid: {detail}. It may have been produced by an incompatible dft version, hand-edited, or truncated. Re-emit it with `dft board emit`.
Fired when a board recording sidecar fails to validate against BoardRecording while loading it for replay.
ERR-BOARD-RECORDING-MISMATCH — Board recording does not match the artifact it was replayed against¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Board recording does not match this artifact: {detail} The artifact and its recording must come from the same `dft board emit` run.
Fired when replaying a resolved-board artifact against a recording that either lacks rows for one of the artifact's queries, or recorded them under different variable values. Both mean the artifact and recording came from different emits (or a truncated one) — replaying anyway would render an empty or wrong chart that looks like real data.
ERR-DUPLICATE-CHART-ID — Two charts share an id across nested faces¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Two charts share the id {chart_id!r} across nested faces, which the flat {format!r} format cannot represent without dropping one. Rename one of them, or use --format json, which keeps the layout nesting.
Chart ids are unique within a face but not across a face tree: two imported partials, or several foreach iterations of one partial, can declare the same id. The flat output formats key charts by id, so a collision would silently drop every chart but the last. Rename the colliding chart, or render with a format that preserves the layout.
ERR-EMITTER-NOT-FOUND — No emitter registered for the resolved chart type¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
No emitter registered for resolved chart type {resolved_type!r}. This indicates an engine bug — the normalizer should have rejected this chart before it reached render.
Fired when the render engine cannot find an emitter for the resolved chart type. This indicates an engine bug; the normalizer should have rejected this chart before it reached render.
ERR-FILE-NOT-FOUND — File not found¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Fired when a file path given to a dataface verb does not exist on the filesystem. Check for typos in the path and ensure the file exists.
ERR-FORMAT-UNSUPPORTED — Unknown render format¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Fired when a render verb is called with an output format that is not supported. Check the supported formats in the CLI reference.
ERR-INTERNAL — Internal error¶
- Level: error
- Domain: unknown
- Suppressible: no
Message template:
Fired when an unclassified internal failure occurs that does not map to a more specific error code. Check the full traceback for details. If this appears in normal usage, file a bug report.
ERR-STARTUP-FAILED — Server failed to start¶
- Level: error
- Domain: serve
- Suppressible: no
Message template:
Fired when the uvicorn server process fails to start. The detail carries the inner error message from uvicorn.
face¶
ERR-EXTRA-FIELD — Unknown field in face YAML¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Fired when the face YAML contains a field name that the schema does not recognize. Remove the unknown field or refer to the YAML reference for the supported keys.
ERR-INVALID-DEFAULT-THEME — Invalid theme name in configuration¶
- Level: error
- Domain: serve
- Suppressible: no
Message template:
Fired when the configured default theme name is not a recognized built-in theme. Check the available theme names and correct the configuration.
ERR-META-SCHEMA — meta.yaml contains an unknown or invalid field¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Fired when a meta.yaml file contains a field that is not recognized by the face schema, or a field with an invalid value. Check that all keys match the supported face fields and remove any extras.
ERR-VALIDATION-FIELD — Face YAML field failed Pydantic validation¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Fired when a face YAML field fails Pydantic's type or constraint validation. The message carries the specific validation error from Pydantic. Check the field value against the schema.
ERR-WRONG-SHAPE — Field expects a mapping but got a scalar¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Field {field_path!r} expects a mapping, not a scalar. Provide a YAML block with keys: {available_keys}.
Fired when a face YAML field that expects a mapping (nested object) receives a plain scalar value instead. Provide a YAML block with the appropriate keys.
layout¶
ERR-NO-LAYOUT — Face defines charts but has no layout¶
- Level: error
- Domain: render
- Suppressible: no
Message template:
Face defines charts ({charts}) but no layout — would render with no visible charts. Add a `rows:`/`cols:`/`grid:`/`tabs:` block that references them.
Fired when a face defines charts but no layout block (rows/cols/grid/tabs). Without a layout, the face would render with no visible charts. Add a layout block that references the charts.
queries¶
ERR-ADAPTER-RELATIVE-PATH-NO-DATA-DIR — Relative source path needs a data directory to resolve against¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Relative {adapter} path {path!r} requires a data_dir to resolve against; none was configured for this adapter. Use an absolute path or configure a data directory.
Fired when a file-backed source (DuckDB, SQLite) declares a relative path: but the adapter has no data directory to resolve it against. Resolving against the process working directory would make the source depend on where dft was invoked from, so Dataface refuses. Use an absolute path or configure a data directory for the project.
ERR-BINDER-TYPE-MISMATCH — Warehouse rejected the query due to a type mismatch¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Warehouse rejected the query due to a type mismatch: {detail}. Add explicit type casts to resolve ambiguity.
Fired when the warehouse reports a type mismatch during query binding. Add explicit type casts to resolve the ambiguity.
ERR-BINDER-UNKNOWN-COLUMN — Warehouse rejected an unknown column or table reference¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Warehouse could not resolve a column or table reference: {detail}. Check that all referenced columns and tables exist in the source.
Fired when the warehouse reports that a column or table reference could not be resolved during query binding. Check that all referenced columns and tables exist in the source.
ERR-DBT-MANIFEST-MISSING — SQL uses a dbt macro but no manifest is available¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
SQL uses {kind} but no dbt manifest was found (looked for {paths}). Build one with `dbt compile`, or commit a manifest.snapshot.json.
Fired when a query's SQL calls ref() or source() but the project has no dbt manifest to resolve the call against. The manifest is what maps a model name to its warehouse relation, so without it Dataface cannot know which table the query means. Run dbt compile (or any command that writes target/manifest.json) in the dbt project, or commit a manifest.snapshot.json next to dataface.yml.
ERR-JINJA-ERROR — Jinja template in a query failed to render¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Fired when a Jinja template in a query or pre-query raises a rendering error. Check the template syntax and ensure all referenced values and filters are available.
ERR-MUTATING-SQL — Non-read-only SQL is not allowed¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
dft refuses to execute non-read-only SQL. Statement: {rejected_node_kind}. Preview: {fragment_preview}.
Fired when Dataface detects a non-SELECT statement (INSERT, UPDATE, DELETE, DROP, etc.) in a query. Dataface only executes read-only SQL to prevent accidental data modification.
ERR-NO-DEFAULT-SOURCE — Source name required but none specified¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Fired when a query reaches execution without a source name and there is no default source configured. Specify a source name on the query or configure a default source.
ERR-QUERY-DURATION-EXCEEDED — Query exceeded the maximum allowed duration¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Fired when a query runs longer than the configured max_query_duration_seconds limit on a source. Optimize the query, raise the limit, or add a WHERE clause to reduce the result set.
ERR-REPO-FILE-TOO-LARGE — Repository file exceeds the 100 MB size limit¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Repo file too large: {file_path} is {size_mb:.1f} MB (limit: 100 MB per file in a connected repo). Use a database connection for data this size.
Fired when a file in a connected repository exceeds 100 MB. Dataface imposes this limit because large files are better served by a direct database connection rather than loading the entire file into memory.
ERR-SOURCE-CONFIG-INVALID — Source configuration fails validation¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Fired when a sources: entry in dataface.yml fails typed SourceConfig validation. Check the source definition for missing required fields or invalid values, and refer to the sources reference for the expected schema.
ERR-SOURCE-CREDENTIAL-LITERAL — Source contains a raw credential literal¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Source {source_name!r}: field {field!r} holds a raw credential literal. dataface.yml is committed to git, so inline secrets leak on push. Reference the secret instead (e.g. {field}: {{{{ env_var('SECRET_NAME') }}}}), or use a `type: dbt_profile` source that delegates to an out-of-repo profiles.yml.
Fired when a sources: entry in the committed dataface.yml contains a raw secret literal (password, API key, etc.). Since dataface.yml is committed to git, inline secrets would be leaked on push. Reference the secret via env_var() or use a dbt_profile source type that delegates to an out-of-repo profiles.yml.
ERR-SOURCE-CROSS-FILE-FORBIDDEN — Cross-file source reference is not allowed¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Fired when a source reference uses the YAML anchor cross-file form (#). Cross-file source references are not allowed; use a named source from the project allowlist instead.
ERR-SOURCE-INLINE-FORBIDDEN — Inline source definition is not allowed¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Query {query_name!r}: inline source definitions are not allowed. Reference a source by name (`source: my_db`) instead. Got: {offending_value}
Fix: Use a named source declared under sources: in your dataface.yml instead of inline connection parameters.
Fired when a query's source: is set to an inline dictionary instead of a named source reference. Inline source definitions are forbidden for security reasons — connection parameters in the committed YAML would leak credentials. Use a named source declared under sources:.
ERR-SOURCE-INVALID-TYPE — Unknown source type¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Fired when a source's type: field names a source type that is not registered. Check for typos and refer to the documentation for the supported source types.
ERR-SOURCE-MISSING-TYPE — Source is missing the required type field¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Fired when a source definition omits the required type: field. Add a type: field naming the source adapter to use.
ERR-SOURCE-NOT-FOUND — Query references an unknown source¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Query {query_name!r} references unknown source {source!r}. Available sources: {available}. dft sources are declared under `sources:` in your dataface.yml — the source name is not the dbt project name.
Fired when a query's source: names a source that is not declared in the sources registry. Check for typos and ensure the source is declared under sources: in your dataface.yml. Also includes the execute-side failure of the same name (source lookup at query time).
ERR-SOURCE-NOT-FOUND-EMPTY — No source profiles are configured¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Source {source!r} not found. No source profiles are configured. Declare sources under `sources:` in your dataface.yml.
Fired when a query references a source but no source profiles are configured at all. Declare sources under sources: in your dataface.yml.
ERR-SOURCE-REQUIRED — Query has no source configured¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Query {query_name!r}: SQL queries must have a source. Set it on the query (`source: my_db`), or at the face or folder meta.yaml level (`source: my_db`).
Fired when a SQL query has no source: set at the query, face, or folder meta.yaml level and no default source is configured. Set source: my_db on the query or as a default at a higher level.
ERR-SQL-LITERAL-NEWLINES — SQL contains literal backslash-n from single-quoted YAML¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Query {query_name!r} {field_label} contains literal \n (backslash + n). Use YAML block scalar `{field_label}: |` to write multiline SQL:
queries:
my_query:
{field_label}: |
SELECT
col
FROM t
Fired when a query's SQL or pre-query string contains a literal backslash followed by 'n', which typically means YAML single-quote escaping swallowed an intended newline. Use a YAML block scalar (field: |) for multiline SQL to avoid this.
ERR-UNKNOWN-QUERY — Chart references an unknown query¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Chart {chart_name!r} references unknown query {query_name!r}. Declare the query under `queries:` or fix the typo in `query:`.
Fired when a chart's query: names a query that is not declared under queries: in the face or any included meta.yaml. Check for typos and ensure the query is declared.
ERR-UNPARSEABLE-SQL — SQL could not be parsed for static checks¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Fix: If the warehouse accepts this query, the SQL is fine — the parser just does not model that dialect or macro yet, and only Dataface's static checks (read-only enforcement, fanout and reaggregation lint) are skipped for it. If the warehouse rejects it too, fix the syntax at the reported position.
Fired when Dataface's static SQL parser cannot parse a query. The query is still sent to the warehouse; what is lost is the static read-only check and the semantic lint that run on parseable SQL. It is not necessarily an error in the SQL itself — unmodelled dialect syntax and dbt macros land here too.
ERR-UNRESOLVED-REFERENCE — Reference points to an unknown name¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
Fired when a chart or layout reference names a target that cannot be found in the current face or any included files. Check for typos and ensure the referenced chart, query, or layout item is declared.
ERR-WAREHOUSE-RUNTIME — Warehouse rejected the query at runtime¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Fired when the warehouse rejects a query for an unclassified runtime error. The detail carries the warehouse's original error message.
variables¶
ERR-STABLE-DOMAIN-OPTIONS-EXCEEDED — Too many variable options to compute a stable axis domain¶
- Level: error
- Domain: execute
- Suppressible: no
Message template:
Computing the stable axis domain for query {query_name!r} would require {option_count} extent queries (limit: {limit}) — variable {variable_name!r}'s static option list is too large to enumerate exhaustively. Set `scale: {{domain_strategy: auto}}` on this chart's axis to opt back into per-filter rescaling, or author an explicit `scale: {{domain: [min, max]}}`.
Fired when computing the stable axis domain for a query would require enumerating more variable option combinations than the configured limit. Set scale: {domain_strategy: auto} on the chart's axis, or author an explicit scale: {domain: [min, max]}.
ERR-UNKNOWN-VARIABLE — Unknown variable referenced in template¶
- Level: error
- Domain: compile
- Suppressible: no
Message template:
{surface} {owner_name!r} references unknown variable {var_name!r}. Declare it under `variables:` or fix the typo.
Fired when a Jinja template references a variable name that is not declared under variables:. Check for typos and ensure the variable is declared before the template that uses it.