cardinality_violation Cardinality Violation — SQLSTATE 21000

A scalar context received more than one row.

• The error is written to the server log and returned to the client carrying SQLSTATE 21000.
• Any driver (libpq, JDBC, psycopg, npgsql, pgx) surfaces this code in its error object so you can branch on it programmatically.
• PL/pgSQL can trap it by name: EXCEPTION WHEN cardinality_violation THEN.

Severity: ERROR  |  PostgreSQL versions: 12, 13, 14, 15, 16, 17

Reproduce with the exact statement and read the full message in the server log (raise log_min_messages / set log_min_error_statement for more context).

A subquery used where a single value is required returned multiple rows, or a multi-row update target was ambiguous.

Common causes:

• A scalar subquery returning more than one row.
• SELECT INTO matching multiple rows.
• An UPDATE ... FROM join producing several source matches per target row.

Steps to resolve 21000:

1. Add LIMIT 1 with a deterministic ORDER BY, or aggregate the subquery.
2. Make join keys unique so each target row matches at most one source row.
3. In PL/pgSQL use SELECT ... INTO STRICT only when exactly one row is guaranteed.

Reference: PostgreSQL error codes — Class 21 (Cardinality Violation).