error: insert or update on table "orders" violates foreign key constraint "orders_user_id_fkey"

Node.js · updated 2026-11-10

Raised by Postgres (SQLSTATE 23503) in two directions: inserting or updating a child row whose reference has no matching parent ("is not present in table"), or deleting or updating a parent that child rows still reference ("is still referenced from table"). node-postgres throws it with error.constraint set, psycopg raises ForeignKeyViolation, Django and SQLAlchemy wrap it as IntegrityError.

error: insert or update on table "orders" violates foreign key constraint "orders_user_id_fkey"
    at node_modules/pg/lib/client.js:694:17
    at process.processTicksAndRejections (node:internal/process/task_queues:103:5)
  code: '23503', constraint: 'orders_user_id_fkey'
  detail: 'Key (user_id)=(22222222-2222-2222-2222-222222222222) is not present in table "users".'

Quick fix

Read the DETAIL line to see which way it failed. "is not present in table" means the parent row does not exist yet (or was deleted, or the id belongs to another environment): create the parent first, in the same transaction. "is still referenced from table" means you are deleting a parent with children: delete the children first, or declare the foreign key ON DELETE CASCADE (or SET NULL) if that is what the data should do.

Read the DETAIL: it names the key column, the value and the other table.
Child insert: check the parent exists with that id in this database; create it first in the same transaction.
Parent delete: decide what should happen to the children (delete them, keep them with null, or refuse) and encode it in the foreign key.
Seeds and imports: load parent tables before child tables.
Check for ids copied between environments (a staging user id used against production).

bash

-- Deleting a user also deletes their orders
alter table orders
  drop constraint orders_user_id_fkey,
  add constraint orders_user_id_fkey
    foreign key (user_id) references users(id) on delete cascade;

Why it happens

Child written before its parent

Two inserts run in the wrong order, or in separate requests where the first one failed.

Deleting a parent that has children

The foreign key has the default NO ACTION, so deleting a referenced user fails while orders still point at it.

An id from somewhere else

A stale id from a cache or the client, or an id from another environment, points at a row this database does not have.

Seed or import order

A seed script or data import loads child tables before the parents they reference.

Other fixes

Use ON DELETE SET NULL to keep child rows (the column must allow null) and ON DELETE RESTRICT to make the refusal explicit.
Return a 409 or a clear message when a delete is refused because of dependent rows, instead of a 500.

Same error, other wording

error: update or delete on table "users" violates foreign key constraint "orders_user_id_fkey" on table "orders"
psycopg.errors.ForeignKeyViolation: insert or update on table "orders" violates foreign key constraint "orders_user_id_fkey"
DETAIL: Key (id)=(11111111-1111-1111-1111-111111111111) is still referenced from table "orders".

Let your coding agent catch the next one

Runheed records this error in production with the stack trace, the breadcrumbs before it and, when you set it, the agent session that shipped the code, and serves it to Claude Code, Cursor or any MCP client. With it connected, you can ask:

> Find the foreign key constraint errors, tell me for each whether a child pointed at a missing parent or a parent delete was blocked, and fix the write order, the id or the ON DELETE rule.

7-day trial, then $29/mo Try it in your agent on sample errors See the setupCancel any time from the billing portal

Setup for Node.js and Express or Vercel Functions, then have your agent fix and resolve it.

Related errors

More in Databases

References: PostgreSQL docs: foreign keys and ON DELETE actions, PostgreSQL docs: error codes (23503 foreign_key_violation)

Spotted a mistake? Email hello@greatwork.company. About Runheed.