Skip to content

Error Handling

dbt charts 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 — including data-shape errors caught while the board is being sized, before any chart is drawn (a pie with a NULL in its theta column, say).

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 board succeed.

One broken chart never blanks the board. Whichever stage catches the problem, it stays scoped to that chart's tile and the rest of the board renders.

When a board 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 (dct 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 dbt charts: Validate Dashboard for the same errors on demand.

CLI

dct validate and dct 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. dct docs errors/dct docs warnings list every code at the CLI, and dct docs errors <CODE>/dct 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.