22003 — numeric_value_out_of_range

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

English manual coverage begins with PostgreSQL 8.1. Source history and runtime observations have their own recorded version boundaries.

Reading PG 18·Select a recorded version

8.1 8.2 8.3 8.4 9.0 9.1 9.2 9.3 9.4 9.5 9.6 10 11 12 13 14 15 16 17 18 19 20

aliases: Unknown
class name: Data Exception
condition name: numeric_value_out_of_range
lang: en
sqlstate: 22003

Definition PG 18

22003

At a glance {#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 {#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 {#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 {#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 {#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 {#versions}

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

Related {#related}

22001 for string length, 22007 for datetime format, and 22008 for datetime field/range overflow.

Sources {#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.

Compare versions

SQLSTATE evidence and recorded runtime versions

cases · integer_out_of_range

{
  "assertions": [
    "SQLSTATE is 22003",
    "The diagnostic identifies integer range overflow",
    "The failed autocommit session remains IDLE",
    "A representable int4 value succeeds afterward"
  ],
  "case_id": "integer_out_of_range",
  "cleanup": "Drop the case schema with an owner connection.",
  "has_snippet": true,
  "position": 0,
  "preconditions": [],
  "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.",
  "trigger": "Cast the decimal text 2147483648 to the target integer type.",
  "versions": [
    "10",
    "18"
  ]
}

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read fixed definition.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "22003 is numeric_value_out_of_range in SQLSTATE Class 22."
}

claims · mechanism.integer-input

{
  "claim_id": "mechanism.integer-input",
  "limits": "This is the selected runtime path; other integer widths have their own input functions.",
  "method": "Read numutils.c out_of_range branch.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.integer-input"
  ],
  "statement": "The integer input routine reports 22003 when a parsed value exceeds the int32 range, with the value and target type in the primary message."
}

claims · mechanism.numeric-format

{
  "claim_id": "mechanism.numeric-format",
  "limits": "This message is not the same as an integer cast failure.",
  "method": "Read numeric.c overflow guard.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.path.numeric-format"
  ],
  "statement": "The numeric factorial path reports 22003 when the result would overflow the numeric format."
}

claims · mechanism.subsystem

{
  "claim_id": "mechanism.subsystem",
  "limits": "The primary message and source object are required to identify the repair.",
  "method": "Read the complete conversion guard.",
  "position": 3,
  "runtime": [],
  "sources": [
    "src.path.width-bucket"
  ],
  "statement": "Other numeric operations such as width_bucket can use a shorter integer-out-of-range message under the same SQLSTATE."
}

claims · history

{
  "claim_id": "history",
  "limits": "",
  "method": "Use catalogue boundary.",
  "position": 4,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records 22003 from 7.4 without proving an exact implementation introduction date."
}

claims · runtime.observation

{
  "claim_id": "runtime.observation",
  "limits": "The observation covers an integer input cast, not the other numeric or subsystem paths.",
  "method": "Execute the shared registry and inspect selected summaries.",
  "position": 5,
  "runtime": [
    "runtime.22003-data1-latest.latest",
    "runtime.22003-data1-pg10.pg10"
  ],
  "sources": [
    "manifest.22003",
    "snippet-registry.22003"
  ],
  "statement": "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."
}

messages · message.integer

{
  "limits": "",
  "message_id": "message.integer",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.integer",
    "primary_template": "value \"%s\" is out of range for type %s",
    "severity_source": "ERROR",
    "sources": [
      "src.path.integer-input"
    ],
    "sqlstate": "22003"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.integer-input"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "value \" \" is out of range for type",
      "position": 0,
      "role": "",
      "template": "value \"%s\" is out of range for type %s"
    }
  ]
}

messages · message.numeric

{
  "limits": "",
  "message_id": "message.numeric",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.numeric",
    "primary_template": "value overflows numeric format",
    "severity_source": "ERROR",
    "sources": [
      "src.path.numeric-format"
    ],
    "sqlstate": "22003"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.numeric-format"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "value overflows numeric format",
      "position": 0,
      "role": "",
      "template": "value overflows numeric format"
    }
  ]
}

messages · message.width-bucket

{
  "limits": "",
  "message_id": "message.width-bucket",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.width-bucket",
    "primary_template": "integer out of range",
    "severity_source": "ERROR",
    "sources": [
      "src.path.width-bucket"
    ],
    "sqlstate": "22003"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.width-bucket"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "integer out of range",
      "position": 0,
      "role": "",
      "template": "integer out of range"
    }
  ]
}

runtimes · runtime.22003-data1-latest.latest · 18.6 (Homebrew) · passed

{
  "cases": [
    "integer_out_of_range"
  ],
  "limits": "",
  "position": 0,
  "raw": {
    "cases": [
      "integer_out_of_range"
    ],
    "id": "runtime.22003-data1-latest.latest",
    "observed": {
      "sqlstate": "22003",
      "status_after_repair": "IDLE"
    },
    "raw": "verify/results/22003-data1-latest/latest/raw.jsonl",
    "raw_sha256": "175423ac2544f055d99352849c7b595f3a7856597282eca042dec0d301f85bb8",
    "run_id": "22003-data1-latest",
    "server_version": "18.6 (Homebrew)",
    "server_version_num": 180006,
    "snippet_registry": {
      "path": "verify/cases/22003/snippets.json",
      "sha256": "6b32f84593ac976a3a39460cd680f9b64bbfd0c62caf1a32b26a561f38a07f2e"
    },
    "status": "passed",
    "summary": "verify/results/22003-data1-latest/latest/summary.json",
    "summary_sha256": "b75b028698e01f0a8d2e46c2cdc8eeb82e95d9bc57bcdd6a036874de387ab0b7",
    "target": "latest"
  },
  "run_id": "22003-data1-latest",
  "runtime_id": "runtime.22003-data1-latest.latest",
  "server_version": "18.6 (Homebrew)",
  "status": "passed",
  "target": "latest"
}

runtimes · runtime.22003-data1-pg10.pg10 · 10.21 (Debian 10.21-1.pgdg90+1) · passed

{
  "cases": [
    "integer_out_of_range"
  ],
  "limits": "",
  "position": 1,
  "raw": {
    "cases": [
      "integer_out_of_range"
    ],
    "id": "runtime.22003-data1-pg10.pg10",
    "observed": {
      "sqlstate": "22003",
      "status_after_repair": "IDLE"
    },
    "raw": "verify/results/22003-data1-pg10/pg10/raw.jsonl",
    "raw_sha256": "00cd428c715f1b196579c4529a65e93a2e7967941a51c0c3d05cb981669a666e",
    "run_id": "22003-data1-pg10",
    "server_version": "10.21 (Debian 10.21-1.pgdg90+1)",
    "server_version_num": 100021,
    "snippet_registry": {
      "path": "verify/cases/22003/snippets.json",
      "sha256": "6b32f84593ac976a3a39460cd680f9b64bbfd0c62caf1a32b26a561f38a07f2e"
    },
    "status": "passed",
    "summary": "verify/results/22003-data1-pg10/pg10/summary.json",
    "summary_sha256": "5ed100d3d0ae588e15638a04477f34541365eaa5832a48b651ad0e3ed7d46a77",
    "target": "pg10"
  },
  "run_id": "22003-data1-pg10",
  "runtime_id": "runtime.22003-data1-pg10.pg10",
  "server_version": "10.21 (Debian 10.21-1.pgdg90+1)",
  "status": "passed",
  "target": "pg10"
}

sources · src.errcodes.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/errcodes.txt",
  "position": 0,
  "sha256": "6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba",
  "source_id": "src.errcodes.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L197"
}

sources · src.calls.REL_18_6

{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "",
  "path": "raw/calls/REL_18_6.jsonl",
  "position": 1,
  "sha256": "9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf",
  "source_id": "src.calls.REL_18_6",
  "tag": "",
  "url": ""
}

sources · src.path.integer-input

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/numutils.c",
  "position": 2,
  "sha256": "9018d559d8a2b04f6d3fa8fedeb754fc5f1f8cd8594292e6adc5108e8f97f1bf",
  "source_id": "src.path.integer-input",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/numutils.c#L603-L612"
}

sources · src.path.numeric-format

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/numeric.c",
  "position": 3,
  "sha256": "6cde7cd60b3330b83be35d1f014045f5fb5fe737f3c5db4c8ed4080b99f2b666",
  "source_id": "src.path.numeric-format",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/numeric.c#L3765-L3769"
}

sources · src.path.width-bucket

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/numeric.c",
  "position": 4,
  "sha256": "6cde7cd60b3330b83be35d1f014045f5fb5fe737f3c5db4c8ed4080b99f2b666",
  "source_id": "src.path.width-bucket",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/numeric.c#L2042-L2046"
}

sources · snippet-registry.22003

{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "",
  "path": "verify/cases/22003/snippets.json",
  "position": 5,
  "sha256": "6b32f84593ac976a3a39460cd680f9b64bbfd0c62caf1a32b26a561f38a07f2e",
  "source_id": "snippet-registry.22003",
  "tag": "",
  "url": ""
}

sources · manifest.22003

{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "",
  "path": "verify/cases/22003/cases.json",
  "position": 6,
  "sha256": "f0416c30e704d445f14a0e53c15116980acd185a6ae0589d5320ad53f5caa7db",
  "source_id": "manifest.22003",
  "tag": "workspace",
  "url": "verify/cases/22003/cases.json"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:ce25e643404a9e7ba43be903af6298402faa8fbff985eac2e1b6d049b34b04ec

Text language: en · english-manuals:ce25e643404a9e7ba43be903af6298402faa8fbff985eac2e1b6d049b34b04ec