- Software and digital services
- Databases
23505
PostgreSQL 23505: unique constraint violation
Risk level
Low
Usually safe to check without specialist tools.
Urgency
Medium
Quick answer
SQLSTATE 23505 is unique_violation. An INSERT or UPDATE attempted to create a value combination that conflicts with a unique constraint or unique index.
Safety first
Stop and check this first
- Do not delete rows or drop a unique constraint as a generic fix for 23505. First identify the named invariant and decide the intended conflict behavior.
Safe checks you can perform
- Read the full database error fields
- Inspect the named uniqueness rule
- Decide whether the duplicate is invalid or expected
Leave these tasks to a qualified professional
- Do not attempt this professional task: Review the write path and concurrency model
What a technician must be able to justify
Technician visit
These are the steps they must carry out and show you. Tick them as they work: if steps are skipped, do not accept a part swap.
These are not instructions for opening or handling the equipment yourself. They are the checks that should support a technical conclusion.
Review the write path and concurrency model
What they doA database engineer should verify transaction boundaries idempotency keys conflict targets and the business invariant behind the unique constraint when 23505 recurs under load.
Before accepting a part or repair
Nothing has been shown yet. Do not accept a part swap based on the code alone.
Follow these steps
Note: Follow the documented order. An error code identifies the affected system, but it does not prove by itself which part has failed.
Read the full database error fields
Capture SQLSTATE 23505 plus the constraint name table and detail exposed by the PostgreSQL driver. Do not diagnose from the numeric code alone.
Redact production values and credentials before sharing logs.
Evidence: PostgreSQL current error codes appendix
Inspect the named uniqueness rule
Confirm which columns or expression the named constraint or index protects and compare the attempted key with the existing row.
Do not drop a uniqueness rule merely to silence the exception.
Evidence: PostgreSQL current error codes appendix
Decide whether the duplicate is invalid or expected
Correct invalid input at its source. If the conflict is an expected idempotent or upsert case define the exact DO NOTHING or DO UPDATE behavior and conflict target.
An overly broad conflict handler can hide genuine data-quality defects.
Evidence: PostgreSQL current INSERT and ON CONFLICT documentation
Still not solved
If the error persists, stop here. See what the technician must do and show you.
Where this code applies
A code is meaningful only inside the right product and version context.
Primary scope
- System
- Software and digital services
- Brand
- PostgreSQL
- Product type
- Databases
Known code variants
- PostgreSQL 23505
- SQLSTATE 23505
- unique_violation
What it means
This is a Class 23 integrity constraint violation. Correct handling depends on whether the duplicate is invalid data an idempotent repeat or an expected conflict that should use an explicit ON CONFLICT policy.
Warnings and stop conditions
- Higheditorial warning
Do not delete rows or drop a unique constraint as a generic fix for 23505. First identify the named invariant and decide the intended conflict behavior.
Evidence: PostgreSQL current error codes appendix · PostgreSQL current INSERT and ON CONFLICT documentation
Symptoms and causes
Probable causes · in order
- Unique constraint violationConfirmed
PostgreSQL assigns SQLSTATE 23505 to unique_violation in the Class 23 integrity-constraint family.
Evidence: PostgreSQL current error codes appendix
- INSERT or UPDATE conflicts with an existing unique keyCommon
A proposed row duplicates a key combination protected by a unique constraint or unique index.
Evidence: PostgreSQL current error codes appendix · PostgreSQL current INSERT and ON CONFLICT documentation
- Expected concurrency conflict lacks an explicit policyPossible
When concurrent or repeated writes are valid business behavior the statement may need a deliberate ON CONFLICT action rather than a generic retry.
Evidence: PostgreSQL current INSERT and ON CONFLICT documentation
Virtual technician
Does 23505 still appear after these checks?
Answer a few questions to narrow down the likely cause and the safest next action. Guidance only - it never replaces a professional.
Sources and technical references
- 1
PostgreSQL current error codes appendix
PostgreSQL Global Development Group · 2026 · official_doc
- 2
PostgreSQL current INSERT and ON CONFLICT documentation
PostgreSQL Global Development Group · 2026 · official_doc
Was this entry useful?