## TL;DR
Incremental models duplicate keys when the unique_key does not match the real grain or when late data bypasses the merge: inspect the duplicates the run created, confirm the unique_key columns in the model configuration, and rebuild the affected window with a correct merge. A full refresh proves the logic; fixing only the symptom rows leaves the next run to duplicate again.

```text
how to fix duplicate primary key failure error on incremental model run
```

## Use this when
- The check or run fails with this symptom: the incremental run creates duplicate rows for the same primary key.
- You are working on an incremental dbt model producing duplicate primary keys and the failure repeats on the same data or configuration.
- You need the failing rows, rule, or stage isolated before changing thresholds or code.

## Not for this skill when
- Duplicates in a full-refresh table with no incremental logic, which points at joins or sources instead.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. List the duplicated keys created by the latest run and the timestamps of the duplicate rows. Verify: the duplicated keys and their run timing are known
2. Read the model's unique_key and incremental strategy in its configuration and compare them with the table's real grain. Verify: the configured key and strategy are explicit
3. Check the incremental filter for a lookback gap that lets corrected or late rows append instead of merge on some runs. Verify: the filter behaviour for late rows is understood
4. Correct the unique_key or strategy, then rebuild the affected date window with the incremental logic, not just a delete of bad rows. Verify: the rebuilt window holds one row per key
5. Run the model twice in a row and confirm the second run changes no row counts, proving idempotency. Verify: two consecutive runs produce stable counts

## Variant phrasings
### duplicate primary key incremental model dbt
The verbatim incremental phrasing.
### dbt incremental unique_key duplicates late data
The late-data phrasing for lookback and merge gaps.
### incremental model not idempotent duplicates on rerun
The idempotency phrasing for repeated runs.

Compatibility: dbt incremental models with unique_key on Snowflake, BigQuery, and Postgres

## Why it happens
Incremental merges rely on the declared unique_key and the run's filter window. A key that omits a grain column, a strategy that appends under some conditions, or late-arriving corrections outside the lookback all insert second copies that only a uniqueness check will catch.

## Edge cases / pitfalls
- Always pair incremental models with a unique test on the declared key. The test is the alarm for this class.
- Keep the lookback window larger than the source's real correction horizon, measured, not guessed.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ux7Iesqe4Xzy2CpkBkT8ZQ