Error de PostgreSQL: null value violates not-null constraint

SQLSTATE 23502 (not_null_violation) · Actualizado 9 de julio de 2026

ERROR:  null value in column "email" of relation "users" violates not-null constraint
DETAIL:  Failing row contains (42, null, Alice, 2026-07-09 10:12:00).

La escritura habría dejado vacía una columna NOT NULL, así que PostgreSQL la rechazó. La línea DETAIL muestra la fila fallida completa, con los valores en el orden de columnas de la tabla — alinéala con la salida de \d y podrás ver exactamente qué llegó.

Qué significa este error

Un mecanismo aquí sorprende a casi todo el mundo en algún momento: los valores por defecto de columna aplican solo cuando la columna se omite del INSERT (o se le da explícitamente la palabra clave DEFAULT). Un INSERT que lista la columna y pasa NULL significa NULL — el default no entra en juego. Los ORM que serializan cada campo mapeado, enviando null para los no establecidos, deshabilitan silenciosamente tus valores por defecto de la base de datos de esta manera.

Causas comunes

• INSERT omitiendo una columna requerida que no tiene default.
• NULL explícito desde la aplicación (el patrón del ORM de arriba) anulando un DEFAULT existente.
• UPDATE estableciendo la columna a NULL, directamente o vía un cálculo que produjo NULL.
• Cargas de datos: en COPY ... CSV, un campo vacío sin comillas se lee como NULL (una cadena vacía entrecomillada "" no lo es).

Cómo diagnosticarlo

\d users   -- qué columnas son NOT NULL, cuáles tienen un DEFAULT

Mapea la fila del DETAIL sobre la lista de columnas para identificar el campo infractor, luego encuentra quién produjo el NULL: el payload de la aplicación, la serialización del ORM, o el archivo de entrada. Registrar el SQL real que envía la app zanja rápido las conversaciones de "¡pero pusimos un default!".

Cómo solucionarlo

• Proporciona el valor, o añade un default genuino: ALTER TABLE users ALTER COLUMN created_at SET DEFAULT now();
• ORM enviando NULLs → configúralo para omitir las columnas no establecidas, o establece el default en el modelo además de en la base de datos.
• Cargas CSV → controla el manejo de NULL explícitamente (opción NULL '', o limpia el archivo); carga en una tabla de staging ante la duda.
• Si NULL es realmente legítimo para el negocio, elimina la restricción deliberadamente: ALTER TABLE users ALTER COLUMN email DROP NOT NULL; — una decisión, no un apaño.