The error
SQLSTATE 23505: duplicate key value violates unique constraint
Quick answer: PostgreSQL identifies SQLSTATE 23505 as a unique-constraint violation. A write attempted to store a key value that conflicts with an enforced unique value.
What this error means
PostgreSQL identifies SQLSTATE 23505 as a unique-constraint violation. A write attempted to store a key value that conflicts with an enforced unique value.
Start with the first application-owned file, operation, request, query, plugin, or component identified by the error. Fix the underlying failure before changing unrelated parts of the application.
Common causes
- The application attempts to insert the same unique value twice.
- A retry or double submission creates a duplicate write.
- An update changes a unique field to an already existing value.
- An application-generated identifier conflicts with an existing key.
- The intended business behavior is insert-or-update but the write does not define conflict handling.
Immediate repair pattern
SELECT * FROM target_table WHERE unique_column = 'duplicate-value';
Apply the repair only when it matches the actual runtime condition shown by the complete error and application context.
Do not hide the root cause
Do not drop a valid unique constraint simply to make the write succeed. First identify the conflicting value and decide whether the duplicate should be rejected, ignored, or intentionally update an existing row.
Repair checklist
- Capture the complete error and stack trace.
- Identify the first application-owned location or resource involved.
- Confirm the runtime value, state, response, or configuration reported by the error.
- Apply the smallest repair that addresses the actual cause.
- Retest both the successful path and the original failing path.
- Confirm the original error no longer occurs.
Still getting the error?
Paste the complete error and stack trace into 0-69. The matching repair engine can classify the failure and prepare specific repair steps and copy-ready code for the detected pattern.
Analyze My PostgreSQL ErrorReference: Official platform documentation