Skip to content

Troubleshooting

Common issues and solutions when working with dbt Charts.

If dct can't reach your data (an adapter that won't import, a profiles.yml it can't find), run dct doctor first. It reports the install method, project, profiles.yml, and per-source adapters in one paste-able block.

How Errors Are Displayed

The current product has a few different error paths, and they do not all render the same way:

  • Parse and validation errors block the render before the dashboard is built.
  • Query execution errors render inline as a negative-tone callout on the failing chart's tile; sibling charts on the same board still render, and the render response still succeeds.
  • Chart data-shape errors can render inline in the affected chart cell, the same way.

For a fuller breakdown, including why a single-chart board's callout can look like a full-page error even though the render succeeded, see Error Handling, which has a live example of one chart's query failing while its neighbor renders normally.

Validation Errors

Missing Required Fields

Error: Missing required field: query

Solution: Ensure all charts have query and type fields:

charts:
  my_chart:
    query: queries.sales  # Required
    type: bar       # Required
    x: month
    y: total_revenue

Invalid Query Reference

Error: Query 'sales' not found

Solution: Ensure the query exists and the name matches exactly:

queries:
  sales:  # Must match chart query reference
    sql: SELECT month, SUM(revenue) AS total_revenue FROM dundersign.orders GROUP BY 1

charts:
  my_chart:
    type: bar
    x: month
    y: total_revenue
    query: queries.sales  # Must match query name

Chart Rendering Issues

Chart Not Displaying

Possible causes: - Query returns no data - Invalid chart configuration - Missing required fields

Solution: 1. Check the query returns data and the resolved chart structure: dct render dashboard.yml --format json --allow-chart-errors 2. Verify chart fields (x, y, type) 3. Check for validation errors: dct validate dashboard.yml

Wrong Chart Type

Error: Chart doesn't match expected type

Solution: - Verify type field matches available chart types - Check Charts Overview - Ensure chart type is supported by Vega-Lite

Data Not Updating

Issue: Chart doesn't update when variable changes

Solution: 1. Verify variable is referenced in query filters 2. Check variable name matches exactly 3. Ensure query re-executes (check query logs)

Variable Problems

Variable Not Updating Query

Issue: Changing variable doesn't update charts

Solution: 1. Verify variable is referenced in the query SQL: 

queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE {{ filter('status', status) }}  # Must reference variable
2. Check variable name matches exactly 3. Ensure the query re-executes after the variable changes

Missing Required Variable

Error: Missing required variables: ...

Solution: 1. Decide whether the variable really needs required: true 2. If it does, supply the value in the board URL query string 3. Or set a variable default: so the board has a renderable starting state

This applies to every chart type. There is no special per-chart recovery path.

Variable Options Not Loading

Issue: Dynamic options not appearing

Solution: 1. Verify query exists and returns data 2. Check query name matches dynamic_query value 3. Ensure query returns the expected column format

Variable Type Mismatch

Error: Variable type doesn't match filter field

Solution: - Ensure data_type matches filter field type - Use appropriate input type for the data type - Check type conversion in expressions if needed

Performance Issues

Slow Dashboard Loading

Possible causes: - Large query results - Complex queries - Multiple queries executing

Solutions: 1. Add a LIMIT clause to queries: 

queries:
  sales:
    sql: SELECT * FROM dundersign.orders LIMIT 100
2. Optimize queries (add filters, aggregate in SQL) 3. Reuse queries across charts 4. Consider caching for static dashboards

Query Timeout

Error: Query execution timeout

Solution: 1. Optimize query (add filters, limit results) 2. Check database performance 3. Bucket timestamps with DATE_TRUNC in SQL instead of grouping by raw timestamps 4. Consider pre-aggregated models

The timeout itself is a server-side statement timeout, enforced on network warehouses (Postgres, Snowflake, BigQuery, etc.); never a client-side abandon. It's configurable via execution.max_query_duration_seconds in dbt_charts.yml, with a per-source override under sources.<name>.max_query_duration_seconds:

# dbt_charts.yml
execution:
  max_query_duration_seconds: 60

sources:
  analytics:
    type: snowflake
    max_query_duration_seconds: 120  # override for this source only

DuckDB and SQLite are local file databases with no server to enforce a timeout; this setting has no effect on them.

dbt Integration Issues

Warehouse Adapter Not Installed

Error: ERR-ADAPTER-NOT-INSTALLED, from a type: dbt_profile source or a direct source alike. dct init prints the same text as a Tip: when it detects a dbt project whose profile needs a missing adapter:

ERR-ADAPTER-NOT-INSTALLED  dbt Charts needs the dbt-snowflake adapter to query
'snowflake' sources, and it is not installed in this Python environment.
Install it with: uv tool install "dbt-charts[snowflake]"

Solution: dbt Charts opens its own connection to your database, through a Python adapter package that ships as an extra. Run the command the error names. It matches how dbt Charts was installed:

uv tool install "dbt-charts[snowflake]"   # or: pip install "dbt-charts[snowflake]"

See Warehouse adapters for the full list. This is about dbt Charts' own connection, not your dbt installation: dbt Charts never runs the dbt command, so it appears whether you build with dbt v1 or dbt v2.

Database Connection Issues

Error: Cannot connect to database

Solution: 1. Check profiles.yml configuration 2. Verify database credentials 3. Test dbt connection: dbt debug 4. Check network/firewall settings

YAML Syntax Errors

Indentation Errors

Error: YAML parsing errors

Solution: - Use spaces, not tabs - Check indentation consistency - Use a YAML validator

Missing Colons

Error: Expected ':'

Solution: - Ensure all keys have colons - Check for typos in field names

Unquoted Special Characters

Error: YAML parsing errors with special characters

Solution: - Quote values with special characters - Use quotes for strings starting with numbers

Getting Help

Validation

Always validate your dashboard first:

dct validate dashboard.yml

See the CLI Reference for more validation options.

Resolved output

Render the resolved layout and executed data as JSON to inspect what each chart actually saw. --allow-chart-errors keeps this from exiting before writing anything when a chart failed:

dct render dashboard.yml --format json --allow-chart-errors

See the CLI Reference for rendering options.

Check Documentation

Common Error Messages

Error Cause Solution
Missing required field Required field not provided Add missing field
Query not found Query name mismatch Check query name spelling
Invalid chart type Unsupported chart type Check chart types reference
YAML syntax error YAML formatting issue Validate YAML syntax
Variable not found Variable name mismatch Check variable name spelling