numeric_value_out_of_range numeric field overflow — 22003

Symptoms

A value exceeds the precision/scale declared for a numeric(p,s) column. PostgreSQL raises SQLSTATE 22003 (numeric_value_out_of_range) with a DETAIL describing the allowed precision.

• The DETAIL explains the column’s precision and scale.
• Often caused by too many digits left of the decimal point.
• Distinct from integer overflow — this is about declared precision.

What the server log shows

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

Why PostgreSQL raises this — what the manual says

Section 8.1.2 Arbitrary Precision Numbers:

“Then, if the number of digits to the left of the decimal point exceeds the declared precision minus the declared scale, an error is raised.”

numeric(p,s) allows p-s digits before the decimal point. A value needing more integer digits cannot be represented and fails with 22003 (fractional excess is rounded, but integer-part excess errors).

Common causes

• A value with too many digits before the decimal point for the column.
• Under-declared precision relative to the data domain.
• Arithmetic producing a larger magnitude than the column allows.

How to fix it

1. Increase precision: ALTER TABLE t ALTER COLUMN amount TYPE numeric(12,2);.
2. Validate the value range before insert.
3. Round/scale intentionally if the extra magnitude is unexpected.

Related & next steps

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

Reference: PostgreSQL 18 Section 8.1 “Numeric Types”.