PostgreSQL Error 22003

SQLSTATE

22003

Condition name

numeric_value_out_of_range

Product

PostgreSQL

Versions

PostgreSQL 13 to 18 (examples run on PostgreSQL 18.6 in PGlite)

Category

Data Exceptions

Last reviewed

24 October 2026

What it means

SQLSTATE 22003 means a number is too large (or too small) for its data type, either when it is stored in a column or while an expression is being calculated.

Each numeric type has a fixed range: smallint holds -32768 to 32767, integer -2147483648 to 2147483647, bigint about plus or minus 9.2 quintillion. A numeric(p, s) column holds at most p digits, s of them after the decimal point, so numeric(5,2) can store up to 999.99. When a value falls outside the range of its type, PostgreSQL raises 22003 (numeric_value_out_of_range) instead of wrapping round or truncating.

The error is just as common in calculations as in stored data. The result of an operation has the type of its inputs, so multiplying two integer columns is done in integer and fails as soon as the product passes 2147483647, even if you only want to display it. The bare message integer out of range does not name the column; check every integer column and expression in the statement. A serial or identity sequence that reaches its maximum raises a different error, nextval: reached maximum value of sequence (SQLSTATE 2200H), but the remedy, moving to bigint, is the same.

Common causes

• An integer expression overflows: counts, cents or milliseconds multiplied together in integer arithmetic.
• A value larger than 2147483647 is stored in an integer column, often an external id, a phone number or a file size in bytes.
• A numeric(p, s) column was sized too small for the values it now has to hold, such as prices above 999.99 in numeric(5,2).
• A smallint column is used for quantities or stock that later exceed 32767.
• A floating point calculation such as power() or exp() overflows double precision.

Diagnose it

Read-only These queries only read the system catalogs (pg_catalog, information_schema) and statistics views such as pg_stat_activity and pg_locks. They do not change data, roles or settings, so they are safe to run first.

SELECT column_name, data_type, numeric_precision, numeric_scale
FROM information_schema.columns
WHERE table_name = 'orders'
  AND data_type IN ('smallint', 'integer', 'bigint', 'numeric', 'real', 'double precision')
ORDER BY ordinal_position;

SELECT max(views) AS highest_views,
       2147483647 - max(views) AS headroom
FROM page_stats;

SELECT schemaname, sequencename, data_type, last_value, max_value,
       round(100.0 * last_value / max_value, 2) AS pct_used
FROM pg_sequences
ORDER BY pct_used DESC NULLS LAST;

How to fix it

Each fix is labelled with what it changes. Try read-only checks and the least invasive fix first, and test changes outside production.

SELECT page_id, views::bigint * 1000 AS views_x1000
FROM page_stats;

ALTER TABLE page_stats
    ALTER COLUMN views TYPE bigint;

ALTER TABLE orders
    ALTER COLUMN total TYPE numeric(12,2);

Examples

Integer multiplication that overflows

3000000 fits in integer, but the product 3000000000 does not. views::bigint * 1000 returns 3000000000.

CREATE TABLE page_stats (page_id int, views int);
INSERT INTO page_stats VALUES (1, 3000000);

SELECT page_id, views * 1000 AS views_x1000 FROM page_stats;

ERROR:  integer out of range

A price too large for numeric(5,2)

CREATE TABLE orders (id int PRIMARY KEY, total numeric(5,2));

INSERT INTO orders VALUES (1, 1234.50);

ERROR:  numeric field overflow
DETAIL:  A field with precision 5, scale 2 must round to an absolute value less than 10^3.

Stock above the smallint range

CREATE TABLE products (id int PRIMARY KEY, stock smallint);

INSERT INTO products VALUES (1, 40000);

ERROR:  smallint out of range

How to prevent it

Use bigint (or bigint GENERATED ALWAYS AS IDENTITY) for surrogate keys and counters that can grow without limit, and do not store external identifiers, phone numbers or byte sizes in integer. Size numeric columns for the largest value the business can produce, not today's.

Watch pg_sequences and the maximum of key columns, and plan type changes long before the limit. In calculations, cast to bigint or numeric before multiplying or summing large values.

Common questions

Learn more on CodeWithSQL

• SQL data types explained
• CAST function

Official documentation

• PostgreSQL error codes (Appendix A)
• Numeric types (ranges and numeric precision)
• ALTER TABLE
• ALTER SEQUENCE

Last technically reviewed 24 October 2026; examples and diagnostics run on PostgreSQL 18.6 (PGlite 0.5.11). SQL-level examples were run in PGlite (PostgreSQL compiled to WebAssembly); examples that need a running server are shown as documented in the PostgreSQL documentation.