↑↓ select ↵ open ⌫ change scope Open full search

PG.CENTER connects PostgreSQL documentation, reference, and ecosystem knowledge. Maintained by Pigsty.

SQLSTATE / CLASS 22 · DATA EXCEPTION

22003

Read PG 18 manual ↗

numeric_value_out_of_range

SQLSTATE
22003
Condition name
numeric_value_out_of_range
Class
Data Exception
Source macro
ERRCODE_NUMERIC_VALUE_OUT_OF_RANGE
Evidence
Observed at runtime in the source evidence
Analysis & operational context

English SQLSTATE atlas: authored explanations and source/runtime evidence are separate from the manual definitions. View source ↗

<h1>22003</h1>

At a glance

22003 is numeric_value_out_of_range. Fixed paths cover integer conversion, numeric overflow, and subsystem-specific range checks; the page centers on numeric conversion and preserves those boundaries.

The shared case casts 2147483648 to integer to capture the range error, then casts 2147483647 as the representable repair. Send the two SELECT statements separately; the first is expected to fail before the repair expression runs. The runner controls the session and cleanup; no schema setup is required.

SELECT '2147483648'::integer;
SELECT '2147483647'::integer;

Calibration observed integer input 2147483648 rejected with value "2147483648" is out of range for type integer; 2147483647 succeeded. The PostgreSQL 18.6 path used pg_strtoint32_safe, while the REL_10_23 source path used pg_atoi; both runner autocommit sessions returned to IDLE.

Messages

The fixed integer input guard raises ERROR with primary value "%s" is out of range for type %s. Other confirmed source paths use value overflows numeric format (numeric factorial) and integer out of range (width_bucket's result conversion). These groups have no separate DETAIL or HINT in the cited source. The selected runtime observed only the integer-input template.

Meaning

22003 covers a numeric or range contract that the selected operation cannot represent. The fixed catalogue member is used by integer conversion, exact-numeric overflow, and subsystem checks; representative messages include integer out of range and value overflows numeric format. Other source paths may use the same SQLSTATE with a different message, so the SQLSTATE alone is not a type diagnosis.

Diagnosis

Read the primary message and source object first. The observed integer case proves only an int4 input-conversion boundary; it does not characterize every numeric expression. For an integer conversion, identify the source and target integer widths and whether the failure occurred during input, assignment, cast, arithmetic, or an extension function. For numeric, distinguish declared precision/scale from arithmetic overflow and preserve the operands and rounding mode. A value can be syntactically valid and still be outside the target range.

Response

Validate the range before the conversion and choose a representation that matches the business contract: reject the value, rescale it explicitly, or use a wider supported type. For arithmetic, inspect intermediate results rather than only the final column. For a subsystem-specific message, repair the named subsystem. The frozen case used autocommit, so the failed cast left the session IDLE; inside an explicit transaction, roll back the transaction or roll back to a pre-existing savepoint before retrying the corrected expression. Do not blanket-retry a deterministic range failure or silently clamp money, identifiers, or counters.

Versions

The locked catalogue records this condition from 7.4 in the listed formal snapshots and 19beta3; fixed source coverage is PostgreSQL 18.6.

Sources

Representative fixed paths include integer input in numutils.c#L603-L612, numeric overflow in numeric.c#L3765-L3769, and the width_bucket result conversion in numeric.c#L2042-L2046. The structured evidence record records the fixed message families and source hashes.

Source evidence

Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.

22003 is numeric_value_out_of_range in SQLSTATE Class 22.

Method: Read fixed definition.

src.errcodes.18.6

The integer input routine reports 22003 when a parsed value exceeds the int32 range, with the value and target type in the primary message.

Method: Read numutils.c out_of_range branch.

Limits: This is the selected runtime path; other integer widths have their own input functions.

src.path.integer-input

The numeric factorial path reports 22003 when the result would overflow the numeric format.

Method: Read numeric.c overflow guard.

Limits: This message is not the same as an integer cast failure.

src.path.numeric-format

Other numeric operations such as width_bucket can use a shorter integer-out-of-range message under the same SQLSTATE.

Method: Read the complete conversion guard.

Limits: The primary message and source object are required to identify the repair.

src.path.width-bucket

The locked catalogue records 22003 from 7.4 without proving an exact implementation introduction date.

Method: Use catalogue boundary.

src.errcodes.18.6

The integer_out_of_range case passed on isolated PostgreSQL 18.6 and 10.21: casting 2147483648 raised 22003, left the autocommit session IDLE, and 2147483647 succeeded.

Method: Execute the shared registry and inspect selected summaries.

Limits: The observation covers an integer input cast, not the other numeric or subsystem paths.

manifest.22003 snippet-registry.22003

Message templates

ERROR · message.integer

Primary

value "%s" is out of range for type %s
ERROR · message.numeric

Primary

value overflows numeric format
ERROR · message.width-bucket

Primary

integer out of range

Reproduction & repair cases

integer_out_of_range · PG 10, 18

Preconditions

    Trigger: Cast the decimal text 2147483648 to the target integer type.

    Expected assertions

    • SQLSTATE is 22003
    • The diagnostic identifies integer range overflow
    • The failed autocommit session remains IDLE
    • A representable int4 value succeeds afterward

    Repair: Use a representable integer or choose a wider numeric type after checking the business range; do not treat a conversion error as a generic data truncation.

    Cleanup: Drop the case schema with an owner connection.

    Recorded runtime evidence

    18.6 (Homebrew) · passed

    Run: 22003-data1-latest

    {
  "sqlstate": "22003",
  "status_after_repair": "IDLE"
}
    10.21 (Debian 10.21-1.pgdg90+1) · passed

    Run: 22003-data1-pg10

    {
  "sqlstate": "22003",
  "status_after_repair": "IDLE"
}

    Definition snapshot: english-manuals:999605ae9224c4ec952e65094be… · English manual source