PostgreSQL Error 23502: Not Null Violation

PostgreSQL error 23502 (Not Null Violation) explained: what it means, why it happens, and how to fix it — with copy-paste code examples.

SQLSTATE 23502 PostgreSQL Last verified 2026-08-19

Quick Answer

Read the error for the exact column that received NULL. If that does not apply, provide an explicit non-null value in the INSERT or fix the application mapping — the full checklist is below.

Error Code

SQLSTATE: 23502
Official name: Not Null Violation
System name: not_null_violation
Service: PostgreSQL

What does this error mean?

A NOT NULL constraint was violated by inserting or updating a column with a NULL value.

Exact Error Messages

You may see this error reported as one of the following messages:

Common Causes

How to Fix

  1. Read the error for the exact column that received NULL
  2. Provide an explicit non-null value in the INSERT or fix the application mapping
  3. Add a DEFAULT or use COALESCE in an UPDATE if nulls can legitimately arrive
  4. Backfill existing NULLs before adding a NOT NULL constraint via migration

Example Scenario

A signup form posts without the email field; the backend builds INSERT INTO users (email, name) VALUES (NULL, 'John') even though email is NOT NULL. PostgreSQL rejects it with SQLSTATE 23502: null value in column "email" of relation "users" violates not-null constraint. The other common variant is adding NOT NULL to an existing column that already contains NULLs — the ALTER TABLE itself fails.

Diagnostic Commands

Run these to confirm the cause before applying a fix — each command answers a specific question.

Which columns are NOT NULL on this table? sql 
SELECT attname, attnotnull
FROM pg_attribute
WHERE attrelid = 'users'::regclass AND attnum > 0 AND NOT attisdropped;

attnotnull = t marks the mandatory columns; cross-check against the columns your INSERT actually sets.

Does the existing data already contain NULLs? sql 
SELECT count(*) FROM users WHERE email IS NULL;

Non-zero means an ALTER TABLE ... SET NOT NULL will fail — backfill first.

Decision Guide

Error on INSERT/UPDATE?
├─ the value is genuinely absent → make it required upstream (form/API validation)
└─ a default exists → use INSERT ... VALUES (DEFAULT, ...)

Error when ALTER TABLE ADD COLUMN NOT NULL?
└─ backfill NULLs first (UPDATE ... SET col = default WHERE col IS NULL),
   then apply the constraint — or add it as NOT VALID and VALIDATE later

Code Examples

Backfill then add NOT NULL sql 
UPDATE users SET email = 'unknown@example.com' WHERE email IS NULL;
ALTER TABLE users ALTER COLUMN email SET NOT NULL;

Never add NOT NULL to a column containing NULLs; backfill first or the constraint fails for existing rows.

Framework-Specific Fixes

prisma

Mark fields as required (non-optional) in schema.prisma; the client will type-check before sending NULL.

model User {
  id    Int    @id @default(autoincrement())
  email String // required, cannot be null
}

django

Use null=False with a default, or validate in clean() before save().

class MyModel(models.Model):
    email = models.EmailField(null=False, default='')

sqlalchemy

Declare nullable=False on the column; the ORM rejects None before reaching the DB.

class User(Base):
    __tablename__ = 'users'
    email = Column(String, nullable=False)

You Might Also Like

23505 Unique Violation A unique constraint or exclusion constraint was violated while inserting or updating a row, because a… 23514 Check Violation A CHECK constraint was violated because a row did not satisfy the constraint expression. MySQL1048 Column Cannot Be Null Column '%s' cannot be null PrismaP2011 Null Constraint Violation Null constraint violation on the {constraint} 22001 String Data Right Truncation A string value was too long for the column's character type and was truncated, which is not allowed.

Frequently Asked Questions

Why am I seeing PostgreSQL error 23502?

Most often this happens when omitting a required column in an INSERT statement, or when passing NULL/undefined from the application for a NOT NULL column.

How do I fix PostgreSQL error 23502?

Read the error for the exact column that received NULL.

Which frameworks have documented fixes for error 23502?

This page documents fixes for: prisma, django, sqlalchemy.

Official Sources

This page is based on the official PostgreSQL documentation linked below and adds practical troubleshooting guidance on top.