SQLSTATE 23503

PostgreSQL foreign_key_violation

A write would leave a child row referencing a parent key that does not exist, or a parent change would orphan dependent rows.

PostgreSQL referential integrityData integritywarning

Exact message

ERROR: insert or update on table violates foreign key constraint

Also searched as: foreign_key_violation · is not present in table

What it means

PostgreSQL enforced the declared relationship between two tables. The failing transaction has an ordering, lifecycle, or identifier problem; disabling the constraint would conceal rather than solve it.

Typical trigger conditions

Creating a child before its parent transaction commits
Deleting a referenced parent without a suitable delete action
Using an identifier from the wrong tenant or environment
Out-of-order event processing

Evidence before intervention

First diagnostic checks

Capture the named constraint

The constraint name identifies the exact relationship and direction that failed.

Inspect relationship actions

Review ON DELETE and ON UPDATE behaviour before changing write order.

SELECT pg_get_constraintdef(oid) FROM pg_constraint WHERE conname = '<constraint_name>';

Verify the parent key

Query the referenced table in the same environment and consider transaction visibility.

Version and platform notes

Referential actions and deferrable constraints are longstanding features; use the documentation matching the deployed version.

Engineering signal

Follow PostgreSQL failures and fixes

One useful weekly email with new error references, tools, integration notes and production lessons. No daily noise.