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.
ERROR: insert or update on table violates foreign key constraintAlso 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
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.
Related engineering templates
Follow PostgreSQL failures and fixes
A useful digest about twice a week with new error references, tools, integration notes and production lessons. No daily noise.