debugging-dbt-errors

dbt Troubleshooting

Read the full error. Check upstream first. ALWAYS run dbt build after fixing.

Critical Rules

1. ALWAYS run dbt build after fixing - compile is NOT enough to verify the fix
2. If fix fails 3+ times, stop and reassess your entire approach
3. Verify data after build - build passing doesn't mean output is correct

Workflow

1. Get the Full Error

dbt compile --select <model_name>
# or
dbt build --select <model_name>

Read the COMPLETE error message. Note the file, line number, and specific error.

2. Inspect Actual Data (For Data Issues)

Before fixing "wrong output" or "incorrect results", query the actual data:

# Preview current output
dbt show --select <model_name> --limit 20

# Check specific values with inline query
dbt show --inline "select * from {{ ref('model_name') }} where <condition>" --limit 10

# Compare with expected - look for patterns
dbt show --inline "select column, count(*) from {{ ref('model_name') }} group by 1 order by 2 desc" --limit 10

Understand what's wrong before attempting to fix it.

3. Read Compiled SQL

cat target/compiled/<project>/<path>/<model_name>.sql

See the actual SQL that will run.

4. Analyze Error Type

Error Type	Look For
Compilation Error	Jinja syntax, missing refs, YAML issues
Database Error	Column not found, type mismatch, SQL syntax
Dependency Error	Missing model, circular reference

5. Check Upstream Models

# Find what this model references
grep -E "ref\(|source\(" models/<path>/<model_name>.sql

# Read upstream model to verify columns
cat models/<path>/<upstream_model>.sql

Many errors come from upstream changes, not the current model.

6. Apply Fix

Common fixes:

Error	Fix
Column not found	Check upstream model's output columns
Ambiguous column	Add table alias: table.column
Type mismatch	Add explicit CAST()
Division by zero	Use NULLIF(divisor, 0)
Jinja error	Check matching {{ }} and {% %}