Skip to content

Troubleshooting

Common issues and solutions when working with Dataface.

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 currently fail the whole render response.
  • Chart data-shape errors can render inline in the affected chart cell.

For a fuller breakdown and the new localhost-only playground error fixtures, see Error Handling.

Example: Query Error

When a query fails (for example, a missing file or bad SQL), the current playground render fails and returns the error:

queries:
  missing_data:
    type: csv
    file: assets/data/this_file_does_not_exist.csv

charts:
  my_chart:
    query: missing_data
    type: bar
    x: date
    y: revenue

You can reproduce this locally with examples/playground/faces/errors/execution-missing-file.yml.

Example: SQL Error

queries:
  bad_sql:
    sql: "SELECT * FROM nonexistent_table"
    source: duckdb_local

charts:
  sql_chart:
    query: bad_sql
    type: table

The render response will include the SQL error message for the failing query.

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 'q_sales' not found

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

queries:
  sales:  # Must match chart query reference
    metrics: [total_revenue]

charts:
  my_chart:
    query: queries.sales  # Must match query name

Query Errors

Metric Not Found

Error: Metric 'total_revenue' not found in Semantic Layer

Solution: 1. Verify the metric exists in your dbt Semantic Layer 2. Check metric name spelling (case-sensitive) 3. List available metrics: mf list metrics

Dimension Not Found

Error: Dimension 'month' not found

Solution: 1. Verify the dimension exists in your Semantic Layer 2. Check dimension name spelling 3. List available dimensions: mf list dimensions

Filter Field Not Found

Error: Filter field 'region' not found

Solution: 1. Ensure the filter field exists in your semantic model 2. Check field name spelling 3. Verify the field is available for filtering

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: dft render dashboard.yml --format json 2. Verify chart fields (x, y, type) 3. Check for validation errors: dft 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 query filters: 

queries:
  sales:
    filters:
      region: region  # Must reference variable
2. Check variable name matches exactly 3. Ensure variable has a valid default value

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 limit to queries: 

queries:
  sales:
    limit: 100
2. Optimize queries (use filters, time_grain) 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. Use time_grain for automatic grouping 4. Consider pre-aggregated models

dbt/MetricFlow Integration Issues

dbt Not Found

Error: dbt: command not found

Solution: 

pip install dbt-core

MetricFlow Not Available

Error: MetricFlow errors

Solution: 

pip install "dbt-core[metricflow]"
# or
pip install metricflow

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:

dft 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:

dft render dashboard.yml --format json

See the CLI Reference for rendering options.

Debug Mode

Enable debug logging:

dft serve dashboard.yml --debug

See the CLI Reference for server 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
Metric not found Metric doesn't exist Verify metric in Semantic Layer
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