22039 — sql_json_array_not_found

An array-only JSON path accessor or item method reached a non-array item without permitted auto-wrap or structural-error suppression. Fixed wildcard, indexed, and .size() paths expose separate array-type primaries; an out-of-bounds subscript is 22033.

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: sql_json_array_not_found
lang: en
sqlstate: 22039

Definition PG 18

22039

At a glance {#at-a-glance}

An array-only JSON path accessor or item method reached a non-array item without permitted auto-wrap or structural-error suppression. Fixed wildcard, indexed, and .size() paths expose separate array-type primaries; an out-of-bounds subscript is 22033.

Messages {#messages}

Representative primary texts are:

| Guard | Primary | | --- | --- | | Wildcard array accessor receives a non-array | jsonpath wildcard array accessor can only be applied to an array | | Indexed array accessor receives a non-array | jsonpath array accessor can only be applied to an array | | .size() receives a non-array without permitted auto-wrap | jsonpath item method .%s() can only be applied to an array |

Meaning {#meaning}

The jpiAnyArray wildcard, jpiIndexArray indexed accessor, and .size() item-method branches can each auto-wrap a non-array item when jspAutoWrap(cxt) is enabled by lax mode. If auto-wrap is not permitted, jspIgnoreStructuralErrors can suppress the structural mismatch; when neither applies, the corresponding array-only branch reports 22039. A valid array with an invalid index reaches the separate 22033 subscript guard, so 22039 does not mean an empty array or an out-of-range index.

Diagnosis {#diagnosis}

Use the exact accessor or method named in the primary and inspect the item returned immediately before it. Separate a scalar/object input from a valid array whose index is outside its bounds, and check whether lax structural-error handling or auto-wrap/unwrap is part of the SQL/JSON path mode.

Response {#response}

Make the path select an array, normalize the input shape, or choose a scalar-compatible operation. If variable documents are expected, handle the scalar/array branch explicitly instead of relying on a structural mismatch to become an empty result. If an ERROR occurred in an explicit transaction, roll back or roll back to the existing savepoint before retrying; autocommit can retry the corrected action.

Versions {#versions}

The locked catalogue records this condition from 12.0; the fixed array accessor and .size() guards are PostgreSQL 18.6. No natural runtime observation is claimed for this page.

Related {#related}

2203C, 2203A, 22033

Sources {#sources}

The wildcard, indexed, and auto-wrap checks are jsonpath_exec.c#L836-979; the .size() array check is #L1101-1117. The strict/lax structural and throw-return macros are #L235-249. The structured evidence record binds the exact array messages and 22033 boundary; 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": "22039 is sql_json_array_not_found 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 wildcard/index and size-method guards, including structural-error suppression and the adjacent subscript boundary.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.jsonpath.array-accessors",
    "src.jsonpath.array-size",
    "src.jsonpath.context-flags",
    "src.jsonpath.execute-context"
  ],
  "statement": "The fixed jpiAnyArray wildcard, jpiIndexArray indexed accessor, and .size() item-method branches can each auto-wrap a non-array item when jspAutoWrap(cxt) is enabled by lax mode. If auto-wrap is not permitted, jspIgnoreStructuralErrors can suppress the structural mismatch; when neither applies, the corresponding array-only branch reports 22039. Array index out-of-bounds is a separate 22033 guard."
}

claims · history

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

messages · message.wildcard-array

{
  "limits": "",
  "message_id": "message.wildcard-array",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.wildcard-array",
    "primary_template": "jsonpath wildcard array accessor can only be applied to an array",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.array-accessors"
    ],
    "sqlstate": "22039"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.array-accessors"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "jsonpath wildcard array accessor can only be applied to an array",
      "position": 0,
      "role": "",
      "template": "jsonpath wildcard array accessor can only be applied to an array"
    }
  ]
}

messages · message.index-array

{
  "limits": "",
  "message_id": "message.index-array",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.index-array",
    "primary_template": "jsonpath array accessor can only be applied to an array",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.array-accessors"
    ],
    "sqlstate": "22039"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.array-accessors"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "jsonpath array accessor can only be applied to an array",
      "position": 0,
      "role": "",
      "template": "jsonpath array accessor can only be applied to an array"
    }
  ]
}

messages · message.size-array

{
  "limits": "",
  "message_id": "message.size-array",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.size-array",
    "primary_template": "jsonpath item method .%s() can only be applied to an array",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.array-size"
    ],
    "sqlstate": "22039"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.array-size"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "jsonpath item method . () can only be applied to an array",
      "position": 0,
      "role": "",
      "template": "jsonpath item method .%s() can only be applied to an array"
    }
  ]
}

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

sources · src.jsonpath.array-accessors

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

sources · src.jsonpath.array-size

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

sources · src.jsonpath.context-flags

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

sources · src.jsonpath.execute-context

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

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:5d026b11496ffcab3614f7a2e515e0f4dc036bf19a05743ee43087dd7561629d

Text language: en · english-manuals:5d026b11496ffcab3614f7a2e515e0f4dc036bf19a05743ee43087dd7561629d