2203C — sql_json_object_not_found

An object-only JSON path accessor or .keyvalue() method received a non-object item. Wildcard member access and object key/value expansion use this structural guard.

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_object_not_found
lang: en
sqlstate: 2203C

Definition PG 18

2203C

At a glance {#at-a-glance}

An object-only JSON path accessor or .keyvalue() method received a non-object item. Wildcard member access and object key/value expansion use this structural guard.

Messages {#messages}

Representative primary texts are:

| Guard | Primary | | --- | --- | | Wildcard member accessor receives a non-object | jsonpath wildcard member accessor can only be applied to an object | | .keyvalue() receives a non-object | jsonpath item method .%s() can only be applied to an object |

Meaning {#meaning}

The wildcard member branch accepts a JSON object; its non-object structural mismatch can be ignored when jspIgnoreStructuralErrors is true, and an array may be auto-unwrapped in lax mode. .keyvalue() may likewise auto-unwrap an array before it requires an object container, but its direct non-object guard uses RETURN_ERROR: throwing versus returning jperError follows jspThrowErrors, as selected by the caller's silent or ON ERROR handling. Lax mode itself does not suppress this direct .keyvalue() guard. Named member access with a missing key is 2203A, while array-only access is 22039.

Diagnosis {#diagnosis}

Use the primary to identify the wildcard accessor or item method, then inspect the current item type. Distinguish an object receiver that lacks a named key from a scalar/array receiver that cannot support object expansion. Check lax auto-unwrap and structural-error handling before treating the result as a missing item.

Response {#response}

Select an object, normalize the input shape, or branch before applying the object-only operation. For wildcard access, use lax structural suppression only when dropping a non-object branch is intended. For .keyvalue(), lax can only unwrap an array first; a remaining non-object follows the direct throw/silent/ON ERROR path, so do not assume lax suppression will ignore it. 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 object-only accessor and .keyvalue() guards are PostgreSQL 18.6. No natural runtime observation is claimed for this page.

Related {#related}

22039, 2203A, 22037

Sources {#sources}

The wildcard member guard is jsonpath_exec.c#L852-874, and .keyvalue() checks its object container at #L2806-2828. The shared strict/lax and throw-return macros are jsonpath_exec.c#L235-249. The structured evidence record binds both object-only primaries; 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": "2203C is sql_json_object_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 wildcard-member and keyvalue object-type guards, including array unwrap and structural-error handling.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.jsonpath.wildcard-member",
    "src.jsonpath.keyvalue-object",
    "src.jsonpath.context-flags",
    "src.jsonpath.execute-context"
  ],
  "statement": "The wildcard member branch requires an object, can ignore a non-object structural mismatch when jspIgnoreStructuralErrors is true, and may auto-unwrap an array in lax mode. .keyvalue() may auto-unwrap an array first, but its direct non-object guard uses RETURN_ERROR; throwing versus returning jperError follows jspThrowErrors and the caller's silent or ON ERROR context. Lax mode itself does not suppress that direct .keyvalue() guard."
}

claims · history

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

messages · message.wildcard-member

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

messages · message.keyvalue-object

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

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

sources · src.jsonpath.wildcard-member

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

sources · src.jsonpath.keyvalue-object

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

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:d0e22ace86901329b1c93975371e1d63d8e00d1733a348765351b8db9da50a24

Text language: en · english-manuals:d0e22ace86901329b1c93975371e1d63d8e00d1733a348765351b8db9da50a24