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: live proof, not just a claim:

title: "One Broken Query, Healthy Neighbor"
source: examples_db

queries:
  revenue_by_date: |
    SELECT date, SUM(revenue) AS revenue
    FROM ecommerce_orders
    GROUP BY date
    ORDER BY date
  missing_table: SELECT * FROM this_table_does_not_exist

charts:
  revenue_chart:
    query: revenue_by_date
    type: line
    x: date
    y: revenue
  broken_chart:
    query: missing_table
    type: table

rows:
  - cols:
      - revenue_chart
      - broken_chart

▶

broken_chart's query fails at runtime (the tile renders the inline tone: negative callout) while revenue_chart renders normally beside it. The render response still succeeds; only chart_errors records the failure.

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 (for example, `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 (for example, `style.charts.bogus_field`)
`hint`	Optional fix suggestion

doc_url isn't stored on the diagnostic itself; look it up from the code in the Error Reference or Warning Reference.

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 (for example, an intentional average of per-group counts) without the warning noise. Three escape hatches exist, each with its own scope. All draw from the same unified diagnostic registry (WARN-* / ERR-* codes); a code typo'd or misspelled in any of them fails loudly 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:
  doc_recipients:
    sql: SELECT AVG(recipient_count) AS avg_recipients FROM (SELECT d.id, COUNT(dr.id) AS recipient_count FROM dundersign.documents d JOIN dundersign.document_recipients dr ON dr.document_id = d.id GROUP BY d.id) per_document
    ignore: [WARN-REAGGREGATION]

charts:
  doc_recipients_chart:
    type: table
    query: doc_recipients
    warnings_ignore: [WARN-QUERY-RETURNED-ZERO-ROWS]

Project-wide: a warnings: block in dbt_charts.yml lists warning codes, query or render, to suppress for every board in the project.

# dbt_charts.yml
warnings:
  ignore:
    - WARN-REDUNDANT-ENCODING

For a single run, dct render --ignore-warning <CODE> suppresses a render warning from the command line.

Every one of these takes a list of codes, never a blanket on/off switch; suppress the specific diagnostic you've reviewed, not every diagnostic on that query, chart, or project. The full list of codes lives in two generated references, which document each code (what it detects, why it fires, how to fix or suppress it): Error Reference and Warning Reference.

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.