Skip to main content

Troubleshooting dbt

When things go wrong with dbt, systematic debugging saves time. This guide covers common issues and their solutions.

Compilation errors​

Syntax errors​

Symptom: dbt compile fails with SQL syntax error

Common causes:

  • Missing commas between columns
  • Unclosed parentheses
  • Invalid SQL syntax

Solution:

  1. Check line numbers in error messages
  2. Validate SQL in your warehouse's query editor
  3. Look for syntax highlighting issues in your IDE
-- Error: Missing comma
select
    customer_id
    customer_name  -- Missing comma here!
    email
from customers

Reference errors​

Symptom: Model 'xxx' not found

Common causes:

  • Typo in model name
  • Model doesn't exist yet
  • Wrong path or naming

Solution:

  1. Verify the model name:
dbt ls | grep model_name
  1. Check for typos in ref():
-- Wrong
{{ ref('cutomers') }}  -- typo!

-- Correct
{{ ref('customers') }}

Jinja errors​

Symptom: Template syntax errors

Common causes:

  • Missing closing tags
  • Invalid variable references
  • Logic errors in macros

Solution:

  1. Check Jinja syntax:
-- Wrong: Missing endif
{% if is_incremental() %}
  where updated_at > (select max(updated_at) from {{ this }})

-- Correct
{% if is_incremental() %}
  where updated_at > (select max(updated_at) from {{ this }})
{% endif %}
  1. Debug Jinja with print:
{{ log('Variable value: ' ~ my_variable, info=True) }}

Connection errors​

Database connection failed​

Symptom: Database connection failed or timeout errors

Common causes:

  • Wrong credentials
  • Network issues
  • Database server down
  • Firewall blocking

Solution:

  1. Test connection directly:
dbt debug
  1. Verify profiles.yml:
my_profile:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: your-account  # Check this!
      user: your-user
      password: your-password
      database: analytics
      warehouse: compute_wh
      schema: dbt_dev
  1. Check environment variables:
echo $SNOWFLAKE_ACCOUNT
echo $SNOWFLAKE_USER

Permission denied​

Symptom: Insufficient privileges or Access denied

Solution:

  1. Verify user has required permissions:
-- As admin, check grants
SHOW GRANTS TO USER dbt_user;
  1. Required permissions:
  • CREATE SCHEMA
  • CREATE TABLE
  • CREATE VIEW
  • SELECT on source tables
  1. Grant permissions:
GRANT USAGE ON WAREHOUSE compute_wh TO ROLE dbt_role;
GRANT USAGE ON DATABASE analytics TO ROLE dbt_role;
GRANT CREATE SCHEMA ON DATABASE analytics TO ROLE dbt_role;

Test failures​

Uniqueness test failed​

Symptom: Uniqueness test failed for column 'xxx'

Causes:

  • Duplicate values in source data
  • Incorrect grain assumption
  • Data quality issues

Solution:

  1. Find duplicates:
select customer_id, count(*)
from {{ ref('stg_customers') }}
group by 1
having count(*) > 1
  1. Check source data quality
  2. Consider composite key if single column isn't unique
  3. Fix upstream data pipeline

Relationship test failed​

Symptom: Relationship test failed - orphaned records

Causes:

  • Referential integrity violation
  • Missing parent records
  • Data loading order issues

Solution:

  1. Find orphaned records:
select o.customer_id
from {{ ref('stg_orders') }} o
left join {{ ref('stg_customers') }} c 
  on o.customer_id = c.customer_id
where c.customer_id is null
  1. Decide strategy:
  • Fix source data
  • Use inner join instead of left join
  • Accept orphanage (remove test)

Accepted values test failed​

Symptom: Accepted values test failed

Solution:

  1. Find unexpected values:
select distinct status
from {{ ref('stg_orders') }}
where status not in ('pending', 'complete', 'cancelled')
  1. Update accepted values or fix source data

Performance issues​

Slow compilation​

Symptom: dbt compile takes too long

Causes:

  • Too many models
  • Complex macros
  • Inefficient Jinja

Solutions:

  1. Use partial parsing:
dbt compile --partial-parse
  1. Reduce macro complexity
  2. Split large projects

Slow model execution​

Symptom: Models take hours to build

Solutions:

  1. Check query plan in warehouse
  2. Add indexes/clustering keys
  3. Use incremental materialization
  4. Optimize joins
  5. Filter early in CTEs

See: dbt Performance Optimization

Out of memory​

Symptom: Out of memory or warehouse crashes

Solutions:

  1. Increase warehouse size temporarily:
{{ config(
    materialized='table',
    snowflake_warehouse='LARGE_WH'
) }}
  1. Process data in batches
  2. Use incremental models
  3. Optimize aggregations

Package issues​

Package not found​

Symptom: Package dbt-labs/dbt_utils not found

Solution:

  1. Check packages.yml:
packages:
  - package: dbt-labs/dbt_utils
    version: 1.1.1
  1. Install packages:
dbt deps
  1. Verify package hub is accessible

Version conflicts​

Symptom: Package version conflicts

Solution:

  1. Pin specific versions:
packages:
  - package: dbt-labs/dbt_utils
    version: [">=1.0.0", "<2.0.0"]
  1. Clear dbt packages:
rm -rf dbt_packages/
dbt deps

Incremental model issues​

Incremental model not updating​

Symptom: Incremental model shows stale data

Solutions:

  1. Check incremental logic:
{% if is_incremental() %}
  where updated_at > (select max(updated_at) from {{ this }})
{% endif %}
  1. Force full refresh:
dbt run --full-refresh --select model_name
  1. Check for schema changes

Duplicate records in incremental model​

Symptom: Incremental model has duplicates

Solutions:

  1. Use merge strategy:
{{ config(
    materialized='incremental',
    unique_key='id',
    incremental_strategy='merge'
) }}
  1. Ensure unique_key is actually unique
  2. Check for late-arriving data handling

Git and version control​

Merge conflicts​

Symptom: Git merge conflicts in dbt files

Solution:

  1. For schema.yml conflicts:
# Accept both changes
git checkout --ours models/schema.yml
git checkout --theirs models/schema.yml
git add models/schema.yml
  1. For SQL files:
  • Manually resolve
  • Test compilation after merge
  • Run full test suite

Schema drift​

Symptom: Tests fail after team member's changes

Solutions:

  1. Run full test suite before merging:
dbt test
  1. Use CI/CD to catch issues
  2. Communicate breaking changes

Debugging techniques​

Enable verbose logging​

dbt run --select model_name --debug
{{ log('My variable: ' ~ my_var, info=True) }}

Check compiled SQL​

# View compiled SQL
cat target/compiled/project_name/models/model_name.sql

Test models in isolation​

# Run single model
dbt run --select model_name

# Run model and children
dbt run --select model_name+

Getting help​

Check logs​

# View recent logs
tail -f logs/dbt.log

# Search for errors
grep "ERROR" logs/dbt.log

Community resources​

  • dbt Slack: #troubleshooting channel
  • GitHub Issues: Check existing issues
  • Documentation: Official dbt docs
  • Discourse: dbt Community forum

Reporting issues​

When reporting issues, include:

  1. dbt version (dbt --version)
  2. Full error message
  3. Relevant model code
  4. profiles.yml (redacted)
  5. Steps to reproduce

FAQ​

Why does dbt compile fail?​

Common causes include syntax errors in SQL, missing references, incorrect Jinja syntax, or missing packages. Check the error message line numbers and verify all dependencies are installed.

How do I fix connection errors?​

Verify your profiles.yml configuration, check credentials are correct, ensure network access to the warehouse, and confirm the database user has proper permissions.

Why are my tests failing?​

Test failures indicate data quality issues. Check the failed records if store_failures is enabled, review recent data loads for anomalies, and verify test logic matches expectations.

How do I debug slow models?​

Check query execution plans in your warehouse, look for missing indexes or clustering keys, review join efficiency, and consider incremental materialization for large datasets.