Duplicate Key Conflict in Incremental Merge

critical

reliabilityUpdated Jan 28, 2026

Detects merge failures in incremental models caused by duplicate unique_key values in source data, preventing proper upsert operations.

Sources

How to Debug dbt Model Failuresoneuptime.com

Troubleshooting common DBT errors and issues - Learn DBTlearndbt.dev

Technologies:

dbtSymptoms of this issue are visible in dbt metrics and logs

dbt.model.incremental.merge_error_count

dbt.model.duplicate_key_count

dbt.database.constraint_violation_count

How to detect:

Monitor for Database Errors during incremental model runs containing messages about unique constraint violations or duplicate key conflicts. Track incremental model failure rates specifically during merge operations.

Recommended action:

Query the source data using a duplicate detection macro to identify problematic records. Add deduplication logic in the is_incremental() block, validate unique_key configuration matches actual data cardinality, or run full-refresh to rebuild the model cleanly.