Skip to content

Error Handling

Dataface currently exposes a few distinct classes of errors, and they do not all behave the same way.

Current Behavior

  • Parse errors stop before compilation finishes.
  • Validation errors stop before rendering starts.
  • Query execution failures and other runtime chart errors render as inline callout cards (tone: negative) while neighboring charts still render.
  • Chart data-shape errors use the same inline callout treatment when the query succeeds but the chart contract is invalid.

For example, a KPI that receives multiple rows renders an inline negative callout while neighboring charts still render successfully. Bad SQL on one chart behaves the same way when other charts on the face succeed.

When a face has only one chart and that chart fails at runtime, the inline callout fills the tile — it can look like a full-page error even though the render response succeeded with chart_errors populated.

Structured Compile Errors

Compile-time failures surface as a list of typed Diagnostic objects.

Each Diagnostic carries:

Field Description
code Machine-readable error code (e.g. ERR-EXTRA-FIELD)
message Human-readable description
range Source file plus 1-indexed start/end line where the error originates, when available
path Dot-separated authoring path to the offending field (e.g. style.charts.bogus_field)
hint Optional fix suggestion

doc_url isn't stored on the diagnostic itself — look it up from the code via the diagnostic registry (dft docs warnings <CODE>).

Playground

The playground renders one card per error — code badge + message + optional line pointer — instead of collapsing all errors into a single block.

VS Code

With the extension's optional language server enabled, compile diagnostics run on save (in addition to fast schema checks on every keystroke) and each Diagnostic maps to a squiggle at the correct source line. The language server is off by default; without it, run Dataface: Validate Dashboard for the same errors on demand.

CLI

dft validate and dft render print each Diagnostic as a Rich panel.

Suppressing a Diagnostic

Some diagnostics are informational rather than fatal — you may want to keep the underlying pattern (e.g. an intentional fanout join) without the warning noise. Two independent escape hatches exist, each scoped to where the diagnostic originates. Both draw from the same unified diagnostic registry (WARN-* / ERR-* codes) — a code typo'd or misspelled in either field fails compilation instead of silently suppressing nothing.

  • Per-query, compile-time: a query's ignore: field lists diagnostic codes to suppress for that query alone.
  • Per-chart, render-time: a chart's warnings_ignore: field lists render-warning codes to suppress for that chart alone.
queries:
  order_totals:
    sql: SELECT o.id, SUM(oi.amount) AS total FROM orders o JOIN order_items oi ON oi.order_id = o.id GROUP BY o.id
    ignore: [WARN-FANOUT-RISK]

charts:
  order_totals_chart:
    type: table
    query: order_totals
    warnings_ignore: [WARN-QUERY-RETURNED-ZERO-ROWS]

Both fields take a list of codes, never a blanket on/off switch — suppress the specific diagnostic you've reviewed, not every diagnostic on that query or chart. The full list of codes lives in two generated references: Error Reference and Warning Reference. dft docs errors/dft docs warnings list every code at the CLI, and dft docs errors <CODE>/dft docs warnings <CODE> print one code's full detector documentation (what it detects, why it fires, how to fix or suppress it) — either verb resolves any registered code, regardless of which list it's actually in.

What Is Not Implemented Yet

Planned behavior not yet implemented:

  • Structured streaming progress and verbosity controls across CLI, MCP, and playground surfaces
  • A larger, policy-driven error-handling model shared across all consumers

If you specifically want to test a raw YAML syntax error such as a missing bracket or colon, paste that broken YAML directly into the playground editor.