integer out of range

Symptoms

An arithmetic result or input value exceeds the range of a 32-bit integer (±2,147,483,647). PostgreSQL raises SQLSTATE 22003 (numeric_value_out_of_range).

• Classic cause: a serial/integer surrogate key approaching 2.1 billion.
• Also from multiplications/sums that overflow int.
• The fix is usually bigint.

What the server log shows

ERROR:  integer out of range

Why PostgreSQL raises this — what the manual says

Section 8.1.1 Integer Types:

“Attempts to store values outside of the allowed range will result in an error.”

integer is a signed 4-byte type. Any input or computed result outside its range cannot be represented, and PostgreSQL raises 22003 instead of wrapping around.

Common causes

• A monotonically increasing serial key reaching the int limit.
• Sums/products overflowing 32 bits.
• Importing values larger than int into an int column.

How to fix it

1. Migrate the column to bigint (and the sequence to bigint): ALTER TABLE t ALTER COLUMN id TYPE bigint;.
2. Cast intermediate arithmetic to bigint to avoid overflow: sum(x::bigint).
3. Use bigserial/bigint for surrogate keys from the start.

Related & next steps

• SQLSTATE 22003 — Numeric Value Out Of Range (full reference)
• Message: bigint out of range
• Glossary: Integer type

Reference: PostgreSQL 18 Section 8.1 “Numeric Types”.