Home / Data Platform / dbt & Quality

Data PlatformTroubleshootingIntermediate

dbt run failures: the common errors and how to fix them fast

Separate compilation, connection, database and test failures in dbt, use the compiled SQL and logs to debug, and rerun only what failed.

Deepak Bhardwaj3 min read

Applies todbt Core 1.7+, dbt Cloud, Snowflake, Databricks, BigQuery, Postgres, Fabric/Synapse adapters

First: what kind of failure?

Output says Type Where to look
Compilation Error Jinja, ref()/source() or YAML problem before any SQL runs The model file and schema.yml
Database Error The warehouse rejected the SQL target/run/<project>/models/...sql (the exact SQL that ran)
Runtime Error ... Could not connect Profile, credentials or network dbt debug
Failure in test A data test found bad rows target/run/.../tests/...sql. Query it to see the rows.

Connection problems

dbt debug                       # checks profiles.yml, credentials and connectivity
dbt debug --config-dir          # shows where dbt looks for profiles.yml

Expired tokens, rotated passwords and a warehouse that's suspended or out of credits all show up here.

Compilation errors

  • Model 'model.proj.stg_orders' depends on a node named 'stg_order' which was not found → a typo in ref(), or the model is disabled.
  • 'dict object' has no attribute ... → a macro or variable missing in this environment. Check vars and env_var() defaults.
  • YAML indentation errors in schema.yml → run dbt parse for a quick check.
dbt compile --select stg_orders     # writes the SQL to target/compiled/... without running it

Database errors

Open the compiled SQL in target/run/... and run it directly in the warehouse to get the full error. Common causes:

Error Fix
Column not found after an upstream change Update the model, or use on_schema_change for incremental models
Incremental model schema mismatch dbt run --select model --full-refresh (rebuilds the table, so mind the size)
Permission denied on a schema The role used by dbt lacks CREATE/USAGE. Fix the grants.
Duplicate key errors in a MERGE The unique_key isn't really unique. Add a test, and deduplicate upstream.

Rerun only what failed

dbt build --select result:error+ --state target/       # failed nodes and their children
dbt retry                                              # dbt 1.6+: re-run from the point of failure
dbt build --select stg_orders+                         # one model and everything downstream

Test failures

dbt test --select stg_orders --store-failures

--store-failures saves the failing rows to a table so you can show the customer exactly which records broke the rule. Decide whether it's a data problem (fix upstream, or quarantine the rows) or a wrong test (adjust it, or set severity: warn with an agreed threshold).

Logs

logs/dbt.log has timing, the full SQL and adapter messages for every run. In dbt Cloud, download the run artifacts or open Debug logs.

Tip

In CI, run dbt build --select state:modified+ --defer --state prod-artifacts/ so pull requests only build what changed, against production models.

Related fixes