Erreur PostgreSQL : null value violates not-null constraint

SQLSTATE 23502 (not_null_violation) · Mis à jour 9 juillet 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).

L'écriture aurait laissé une colonne NOT NULL vide, donc PostgreSQL l'a rejetée. La ligne DETAIL montre toute la ligne en échec, avec les valeurs dans l'ordre des colonnes de la table — alignez-la sur la sortie de \d et vous voyez exactement ce qui est arrivé.

Ce que signifie cette erreur

Un mécanisme ici surprend presque tout le monde à un moment donné : les valeurs par défaut des colonnes ne s'appliquent que lorsque la colonne est omise de l'INSERT (ou explicitement dotée du mot-clé DEFAULT). Un INSERT qui liste la colonne et passe NULL signifie NULL — la valeur par défaut ne s'active pas. Les ORM qui sérialisent chaque champ mappé, envoyant null pour ceux non renseignés, désactivent silencieusement vos valeurs par défaut de base de cette manière.

Causes fréquentes

• INSERT omettant une colonne obligatoire qui n'a pas de valeur par défaut.
• NULL explicite depuis l'application (le schéma d'ORM ci-dessus) écrasant un DEFAULT existant.
• UPDATE fixant la colonne à NULL, directement ou via un calcul ayant produit NULL.
• Chargements de données : dans COPY ... CSV, un champ vide sans guillemets est lu comme NULL (une chaîne vide entre guillemets "" ne l'est pas).

Comment la diagnostiquer

\d users   -- quelles colonnes sont NOT NULL, lesquelles ont un DEFAULT

Mappez la ligne DETAIL sur la liste des colonnes pour identifier le champ fautif, puis trouvez qui a produit le NULL : la charge utile de l'application, la sérialisation de l'ORM, ou le fichier d'entrée. Journaliser le SQL réel que l'application envoie tranche vite les conversations « mais on a défini une valeur par défaut ! ».

Comment la corriger

• Fournissez la valeur, ou ajoutez une vraie valeur par défaut : ALTER TABLE users ALTER COLUMN created_at SET DEFAULT now();
• ORM envoyant des NULL → configurez-le pour omettre les colonnes non renseignées, ou définissez la valeur par défaut dans le modèle en plus de la base de données.
• Chargements CSV → contrôlez la gestion des NULL explicitement (option NULL '', ou nettoyez le fichier) ; chargez dans une table de staging en cas de doute.
• Si NULL est réellement légitime pour le métier, supprimez la contrainte délibérément : ALTER TABLE users ALTER COLUMN email DROP NOT NULL; — une décision, pas un contournement.