Tracing a bug back through dbt's compiled SQL

When a dbt model fails, the error often comes from the compiled SQL, not the Jinja source, since Jinja/macros/ref() calls resolve before the SQL reaches the warehouse. Checking the compiled code in the target/compiled directory (or the 'Compiled code' tab in dbt Cloud) shows exactly what the warehouse executed, making it the fastest way to isolate syntax or logic errors. Running the compiled SQL directly in your warehouse's query editor lets you iterate quickly without waiting for dbt to re-run the full Jinja compilation each time.

1 · Learn the must-know

• 1Compiled SQL lives in target/compiled/<project_name>/models/... and mirrors the exact file/folder path of the source model.
• 2target/run/ contains the actual SQL that was executed against the warehouse (post-compilation, including any adapter-specific wrapping), which can differ slightly from target/compiled for incremental or materialization logic.
• 3Use dbt compile (or dbt run --select model_name) to regenerate compiled files before inspecting them, since stale target/ artifacts can mislead debugging.
• 4Copy-pasting compiled SQL into your warehouse's native SQL editor lets you test fixes, check row counts, and inspect intermediate CTEs faster than repeatedly invoking dbt.
• 5Errors referencing ref() or source() failures usually indicate a graph/compilation-time problem, while errors on the raw SQL syntax usually indicate a compiled-code problem, so identifying which stage failed narrows debugging quickly.
• 6The target/ directory is gitignored and regenerated per invocation, so always re-run dbt compile after changing a model or its Jinja logic before trusting the compiled output.

2 · Check your understanding