PostgreSQL unique_violation
An INSERT or UPDATE attempted to create a value combination already protected by a unique constraint or index.
ERROR: duplicate key value violates unique constraintAlso searched as: unique_violation · duplicate key
What it means
The database preserved uniqueness and rejected the statement. This may represent an expected race that needs conflict handling, a faulty identifier generator, or application logic that assumed a record did not exist.
Typical trigger conditions
- Concurrent create requests
- Replayed messages or retries without idempotency
- A sequence behind the maximum stored identifier
- An incorrect natural-key assumption
First diagnostic checks
Read the constraint and key detail
Use the named constraint and conflicting values from the server error rather than guessing the affected column.
Inspect the constraint definition
Confirm which columns and expressions enforce uniqueness.
SELECT pg_get_constraintdef(oid) FROM pg_constraint WHERE conname = '<constraint_name>';
Check retry semantics
Decide whether the operation should use ON CONFLICT, return the existing record, or fail visibly.
Version and platform notes
INSERT ... ON CONFLICT is available from PostgreSQL 9.5 onward; conflict behaviour must still match the business operation.
Follow PostgreSQL failures and fixes
One useful weekly email with new error references, tools, integration notes and production lessons. No daily noise.