“Failing Row Contains” — Read a SQL Constraint Error

The symptom

PostgreSQL rejects an INSERT or UPDATE and adds a detail line like "Failing row contains (...)". The statement did not quietly skip that row; it failed because the row would break a rule on the table. PostgreSQL prints that line for a NOT NULL or CHECK failure. A unique or foreign key failure gets a Key (...) line instead, naming only the key.

The garden_shop practice tables load straight from CSV and carry no constraints of their own, so the bench below declares a small table with three rules on it: a primary key, a unique email, and a check on the plan. Only one of them fires, and it is the kind that produces a failing-row line. Read the message to find out which, then switch to the fix.

DuckDB reports this as Constraint Error: CHECK constraint failed on table signup with expression CHECK((plan IN ('free', 'pro'))). The second row asks for a team plan the rule does not allow. Notice what the message gives you: the table and the rule that fired. It does not print the row at all. PostgreSQL, where this page's title phrase comes from, names the constraint (signup_plan_check) and adds DETAIL: Failing row contains (2, ben@example.com, team)., every value in the rejected row, which is why the phrase became a common thing to search for.

Read the line before the row

The values inside failing row contains are evidence, not the root cause. The real clue is the line above it, which names the violated constraint. Only a NOT NULL or CHECK failure prints the row; a UNIQUE, primary key, or foreign key failure names the key instead. Either way, the constraint tells you where to go next.

Debug the rejected row

Turn the values from the error into a small SELECT. Confirm what is missing or duplicated before changing the data.

select customer_id, first_name, last_name, email
from customers
where customer_id = 5;

A row comes back, so customer_id 5 is taken: an insert claiming it would collide. Run the same query for a key the error named and getting nothing back tells you the opposite story: that is the shape of a missing parent rather than a duplicate.

select customer_id
from customers
where customer_id = 42;

-- No rows: an order for customer_id 42 would violate a foreign
-- key that requires customers.customer_id.

Fix the data or the rule

Most of the time, the fix is the data: provide the required value, use a valid status, choose a new key, or create the parent row before the child row. Change the table constraint only when the rule itself is wrong.

create or replace table signup (
  id integer primary key,
  email varchar unique not null,
  plan varchar check (plan in ('free', 'pro'))
);
insert into signup values (1, 'ada@example.com', 'free');
insert into signup values (2, 'ben@example.com', 'team');

create or replace table signup (
  id integer primary key,
  email varchar unique not null,
  plan varchar check (plan in ('free', 'pro'))
);
insert into signup values (1, 'ada@example.com', 'free');
insert into signup values (2, 'ben@example.com', 'pro');

insert into customers (customer_id, first_name, email)
values (42, 'Ada', 'ada@example.com');

How other engines word it

Which engines show you the row

Engines usually identify the rule or object that rejected the write. They differ in whether they name a declared constraint and whether they include the rejected values, which determines how much investigation remains.

Related errors

• Fix “NOT NULL Constraint Failed” in SQL

  A required column got no value. Supply one, give the column a default, or let it be null.

• Fix “Duplicate Key Violates Primary Key Constraint” in SQL

  The key you are inserting already exists. Find the existing row before you write.

• Fix “Violates Foreign Key Constraint” in SQL

  A child row points at a parent that is not there, or a parent still has children.

Learn more

• SQL error messages explained
• Reference · Table constraints
• Reference · Safe UPDATE & DELETE
• Lesson 9.1 · Reading error messages
• Lesson 8.5 · Transactions and ROLLBACK