## 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

```text
Database Error: deadlock detected during dbt run
```

## Steps

1. 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.

2. 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.

3. 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.

4. 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