Database Error: deadlock detected during dbt run
Fixes warehouse deadlocks during dbt runs for analytics engineers and repair agents. Use when the database reports a deadlock while dbt models build. Not for statement timeouts or lock waits that eventually clear.
TL;DR
Two sessions grabbed the same tables in opposite order, usually dbt threads plus an outside writer. Drop dbt threads to 1 for the conflicting models, or stagger the jobs so writers never overlap. If it recurs, make the contended models run sequentially with a +model selector chain.
Error
Database Error: deadlock detected during dbt runSteps
Check the warehouse's lock or deadlock log for the two statements involved and which tables they touched. Expected: You see two sessions locking the same tables in opposite order, one of them from dbt.
Find the other writer: another dbt run, an ELT sync, or a manual session. Check your orchestrator for overlapping schedules. Expected: You identify the overlapping job, e.g. an hourly sync landing while dbt builds the same schema.
Separate them: shift one schedule, or run the contended models with --threads 1, or split them into their own dbt invocation that runs alone. Expected: No overlapping writes on the same tables in the same window.
Re-run. If deadlocks persist, look for a model that writes to a table it also reads, and split the read and write into separate models. Expected: Clean run, no deadlock errors.
When to use
- warehouse reports deadlock detected while dbt runs
- deadlocks started after you raised threads or added a parallel job
- incremental models that delete and insert in the same transaction deadlock
When not to use
- statement timeout or canceling statement (that is a timeout, not a lock cycle)
- a single slow query with no second session involved
- the error names only dbt Cloud infrastructure, not the warehouse
Tool compatibility
- Postgres and Redshift report deadlocks most explicitly
- Snowflake: check QUERY_HISTORY for overlapping writes on the same tables
- dbt --threads flag controls dbt-side parallelism
Variant phrasings
deadlock on dbt snapshot
Snapshots lock the target table while merging. Do not run two snapshots of the same table concurrently, and keep snapshot runs away from the main dbt run window.
deadlock only on full-refresh
Full refresh drops and recreates, which escalates locks. Schedule full refreshes in a quiet window.
Why it happens
Deadlock needs two sessions and opposite lock order. dbt's threads make one session many, and incremental strategies like delete+insert hold write locks across the transaction. Add any outside writer on the same tables and the cycle forms.
Edge cases
- Postgres aborts only the deadlocked statement and dbt fails the model; the other session keeps going, so partial state is possible, re-run the model.
- Retrying immediately often re-deadlocks if the other job is still running; wait for the window to clear first.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_YcPZDVDn7Dczd3U8jzQoLw