PostgreSQL 23505 unique_violation: clave duplicada en una tabla

Aviso: Sigue el orden documentado. Un código identifica el sistema afectado, pero por sí solo no demuestra qué pieza está averiada.

1. 1

   Nombre de la restricción en el error

   Sin herramientas especiales

   Quién:

   desarrollador o administrador de la base de datos.

   Cómo:

   lee el campo de nombre de restricción del error (campo n del protocolo) y los de esquema y tabla, no solo el texto traducido del mensaje.

   Resultado que importa:

   qué restricción o índice único se ha violado.

   Si es la clave primaria:

   apunta a datos repetidos o a una secuencia desfasada.

   Si es otra restricción única:

   indica una regla de negocio; revisa sus columnas.

   Evidencia a conservar:

   registro del error completo con sqlstate, restricción y tabla.

   Evidencia: PostgreSQL current error codes appendix · PostgreSQL error and notice fields

2. 2

   Definición de la restricción

   Sin herramientas especiales

   Quién:

   desarrollador o administrador de la base de datos.

   Cómo:

   consulta pg_indexes para ver la indexdef del índice afectado: columnas, predicado parcial y NULLS NOT DISTINCT.

   Resultado que importa:

   qué combinación de columnas debe ser única.

   Si incluye columnas que no esperabas:

   confirma que la restricción es más estricta que la lógica de la aplicación.

   Si coincide con lo esperado:

   descarta la definición y busca el dato repetido.

   Evidencia a conservar:

   copia de la indexdef consultada.

   Evidencia: PostgreSQL current pg_indexes system view · PostgreSQL constraints

3. 3

   Fila que ya tiene el valor

   Sin herramientas especiales

   Quién:

   desarrollador o administrador de la base de datos.

   Cómo:

   ejecuta un SELECT filtrando por los valores que intentabas guardar en las columnas de la restricción.

   Resultado que importa:

   si existe ya una fila con ese valor.

   Si aparece una fila:

   confirma el duplicado; decide si actualizar esa fila o rechazar la entrada.

   Si no aparece y la columna es id con secuencia:

   apunta a la secuencia o a una escritura concurrente.

   Evidencia a conservar:

   resultado de la consulta y hora.

   Evidencia: PostgreSQL current error codes appendix · PostgreSQL constraints

4. 4

   Secuencia frente al máximo de la columna

   Requiere herramientas

   Quién:

   administrador de la base de datos.

   Cómo:

   compara el último valor de la secuencia con el máximo de la columna id; si va por detrás, ajústala con setval tras revisar el impacto.

   Resultado que importa:

   si nextval va a devolver valores ya usados.

   Si la secuencia está por debajo del máximo:

   confirma la causa; tras setval el siguiente nextval avanza desde ese valor.

   Si va por delante:

   descarta la secuencia y revisa la concurrencia.

   Evidencia a conservar:

   valores antes y después del ajuste.

   Cambiar una secuencia en producción afecta a todas las inserciones: no lo hagas sin permisos de administrador ni sin copia de seguridad.

   Evidencia: PostgreSQL sequence manipulation functions

Un código solo tiene significado dentro del producto y la versión correctos.

PostgreSQL clasifica 23505 como unique_violation dentro de la clase 23, violación de restricción de integridad. Salta cuando dos filas de la tabla quedarían con valores iguales en todas las columnas de una restricción UNIQUE, de una clave primaria o de un índice único. El servidor envía el nombre de la restricción o del índice en un campo propio del error. Por defecto dos NULL no se consideran iguales. El código no dice si el duplicado viene de datos repetidos, de una secuencia desfasada o de dos transacciones simultáneas.

• Precauciónadvertencia editorial

  No elimines la restricción única para que desaparezca el error: dejarías entrar duplicados que la restricción existe para impedir.

  Evidencia: PostgreSQL constraints

• Seguroverificada con fuente

  No analices el texto del mensaje para decidir: PostgreSQL recomienda usar el código de error y los campos separados, porque el texto puede traducirse o cambiar.

  Evidencia: PostgreSQL current error codes appendix

1. 1

   PostgreSQL current error codes appendix

   PostgreSQL Global Development Group · 2026 · official_doc

2. 2

   PostgreSQL current INSERT and ON CONFLICT documentation

   PostgreSQL Global Development Group · 2026 · official_doc