22033 — invalid_sql_json_subscript

A SQL/JSON array subscript is invalid. Fixed jsonpath paths distinguish out-of-bounds, non-single-numeric, and integer-range variants.

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

12 13 14 15 16 17 18 19 20

aliases: Unknown
class name: Data Exception
condition name: invalid_sql_json_subscript
lang: en
sqlstate: 22033

Definition PG 18

22033

At a glance {#at-a-glance}

A SQL/JSON array subscript is invalid. Fixed jsonpath paths distinguish out-of-bounds, non-single-numeric, and integer-range variants.

Messages {#messages}

The fixed subscript guards use these primary texts:

| Guard | Primary | | --- | --- | | subscript is not one numeric item | jsonpath array subscript is not a single numeric value | | numeric subscript outside int32 | jsonpath array subscript is out of integer range | | strict array bound failure | jsonpath array subscript is out of bounds |

Meaning {#meaning}

The jsonpath executor evaluates each subscript expression as a result list. getArrayIndex requires exactly one numeric scalar, truncates it to an integer, and reports 22033 when the result is not a single numeric item or cannot fit the integer range. The later array-bound guard reports the same code for a negative start, reversed range, or upper bound past the array in strict mode. Lax mode ignores that structural out-of-bounds error and clamps the range to the available array; it does not turn a non-numeric or overflowing subscript into a valid index.

Diagnosis {#diagnosis}

Inspect the subscript expression’s cardinality and type before inspecting array length. A path that yields multiple items, a non-numeric value, or an integer overflow uses the conversion messages; a numeric index or range that violates strict array bounds uses the out-of-bounds message. Record whether the path is strict or lax, because lax structural handling can produce an empty or clamped result instead of this ERROR. A later no-item behavior is 22035 when its SQL/JSON operation chooses to raise it.

Response {#response}

Make the subscript expression return one finite numeric value in the integer range, and keep strict-mode bounds within the target array with a non-reversed range. If lax clamping or an empty result is intended, confirm that the path mode and surrounding SQL/JSON behavior express that intent. If an ERROR occurred in an explicit transaction, roll back or roll back to the existing savepoint before retrying; autocommit can retry the corrected expression.

Versions {#versions}

The locked catalogue records this condition from 12.0; the fixed jsonpath source paths here are PostgreSQL 18.6. No natural runtime observation is claimed for this page.

Related {#related}

22034, 22035

Sources {#sources}

Array-bound handling is src/backend/utils/adt/jsonpath_exec.c#L892-929. Subscript cardinality, truncation, and integer conversion are #L3442-3477. The structured evidence record retains all three 22033 guard roles; no natural runtime was run.

Compare versions

SQLSTATE evidence and recorded runtime versions

claims · identity

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

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "Source confirmation is not a natural runtime observation.",
  "method": "Read the complete array-subscript execution and getArrayIndex conversion guards.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.0",
    "src.jsonpath.subscript"
  ],
  "statement": "The fixed jsonpath executor evaluates each subscript to one numeric item, truncates it to int32, and raises 22033 for a non-single numeric result or integer-range overflow; strict mode also raises for invalid array bounds, while lax mode ignores structural out-of-bounds errors and clamps the range."
}

claims · history

{
  "claim_id": "history",
  "limits": "",
  "method": "Use catalogue boundary.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records 22033 from 12.0 without proving exact implementation introduction."
}

messages · message.0

{
  "limits": "",
  "message_id": "message.0",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.0",
    "primary_template": "jsonpath array subscript is out of bounds",
    "severity_source": "ERROR",
    "sources": [
      "src.path.0"
    ],
    "sqlstate": "22033"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.0"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "jsonpath array subscript is out of bounds",
      "position": 0,
      "role": "",
      "template": "jsonpath array subscript is out of bounds"
    }
  ]
}

messages · message.non-single-numeric

{
  "limits": "",
  "message_id": "message.non-single-numeric",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.non-single-numeric",
    "primary_template": "jsonpath array subscript is not a single numeric value",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.subscript"
    ],
    "sqlstate": "22033"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.subscript"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "jsonpath array subscript is not a single numeric value",
      "position": 0,
      "role": "",
      "template": "jsonpath array subscript is not a single numeric value"
    }
  ]
}

messages · message.integer-range

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

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#L218"
}

sources · src.path.0

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/jsonpath_exec.c",
  "position": 1,
  "sha256": "678cb8947f0b5e6ad14524f1863987ab99641cfb5f81121fc5c5006af0319d02",
  "source_id": "src.path.0",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L919"
}

sources · src.jsonpath.subscript

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/jsonpath_exec.c",
  "position": 2,
  "sha256": "678cb8947f0b5e6ad14524f1863987ab99641cfb5f81121fc5c5006af0319d02",
  "source_id": "src.jsonpath.subscript",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L3442"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:62345a52ad8568970803b546a99bd80246940387fcce56bc7097f29d9aa6e7e2

Text language: en · english-manuals:62345a52ad8568970803b546a99bd80246940387fcce56bc7097f29d9aa6e7e2