22034 — more_than_one_sql_json_item

A SQL/JSON query returned more than one item where the operation requires one. Fixed JSONQUERY/JSONVALUE paths report single-item or single-scalar requirements and may hint to use WITH WRAPPER.

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: more_than_one_sql_json_item
lang: en
sqlstate: 22034

Definition PG 18

22034

At a glance {#at-a-glance}

A SQL/JSON query returned more than one item where the operation requires one. Fixed JSON_QUERY/JSON_VALUE paths report single-item or single-scalar requirements and may hint to use WITH WRAPPER.

Messages {#messages}

The no-wrapper cardinality guards use these primary texts:

| Operation | Primary and hint | | --- | --- | | JSON_QUERY column without wrapper | JSON path expression for column "%s" must return single item when no wrapper is requested; HINT: Use the WITH WRAPPER clause to wrap SQL/JSON items into an array. | | JSON_QUERY without a column name | JSON path expression in JSON_QUERY must return single item when no wrapper is requested; HINT: Use the WITH WRAPPER clause to wrap SQL/JSON items into an array. | | JSON_VALUE with more than one item | JSON path expression in JSON_VALUE must return single scalar item |

Meaning {#meaning}

The fixed JSON_QUERY path collects the complete SQL/JSON result list and counts it before applying the wrapper mode. Without a wrapper, more than one item raises 22034; unconditional or conditional WITH WRAPPER turns the sequence into an array according to its mode. JSON_VALUE uses the same code when more than one item is returned, because it requires one scalar. Exactly one non-scalar item is a separate 2203F condition, and zero items set the empty flag for ON EMPTY handling. Lax auto-unwrapping can change the result cardinality; silent or non-ERROR ON ERROR behavior can suppress an evaluation error before the cardinality guard is reported.

Diagnosis {#diagnosis}

Record the operation (JSON_QUERY or JSON_VALUE), wrapper clause, column name, and number of items produced by the path. For JSON_QUERY, use WITH WRAPPER only when an array result is intended; for JSON_VALUE, reduce the path to one scalar rather than wrapping. Distinguish multiple items (22034), one non-scalar item (2203F), and no items handled by ON EMPTY/22035. Check strict/lax and silent settings because they affect the sequence seen by this guard.

Response {#response}

Change the path or filter to return one required item, or add the documented wrapper when the consumer expects an array. For JSON_VALUE, also ensure the one item is scalar. If the operation uses an ON ERROR behavior, keep its fallback consistent with the intended cardinality rather than treating NULL as proof that the path returned one item. 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 SQL/JSON cardinality paths here are PostgreSQL 18.6. No natural runtime observation is claimed for this page.

Related {#related}

22033, 22035

Sources {#sources}

JSON_QUERY wrapper and multi-item guards are src/backend/utils/adt/jsonpath_exec.c#L3880-4005. JSON_VALUE’s multiple-item and scalar distinction is #L4008-4070. The structured evidence record retains the wrapper, cardinality, and hint 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": "22034 is more_than_one_sql_json_item in SQLSTATE Class 22."
}

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "Source confirmation is not a natural runtime observation.",
  "method": "Read JsonPathQuery and JsonPathValue cardinality, wrapper, and scalar guards.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.0",
    "src.jsonpath.cardinality"
  ],
  "statement": "The fixed JSON_QUERY path collects the complete SQL/JSON result list, uses the wrapper mode to permit multiple items, and emits 22034 only when more than one item remains without a wrapper; JSON_VALUE uses the same code for more than one item, while a single non-scalar is the separate 2203F condition."
}

claims · history

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

messages · message.0

{
  "limits": "",
  "message_id": "message.0",
  "path": "",
  "position": 0,
  "raw": {
    "hint_template": "Use the WITH WRAPPER clause to wrap SQL/JSON items into an array.",
    "id": "message.0",
    "primary_template": "JSON path expression for column \"%s\" must return single item when no wrapper is requested",
    "severity_source": "ERROR",
    "sources": [
      "src.path.0"
    ],
    "sqlstate": "22034"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.0"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "JSON path expression for column \" \" must return single item when no wrapper is requested",
      "position": 0,
      "role": "",
      "template": "JSON path expression for column \"%s\" must return single item when no wrapper is requested"
    },
    {
      "kind": "hint",
      "literal": "Use the WITH WRAPPER clause to wrap SQL/JSON items into an array.",
      "position": 1,
      "role": "",
      "template": "Use the WITH WRAPPER clause to wrap SQL/JSON items into an array."
    }
  ]
}

messages · message.json-query

{
  "limits": "",
  "message_id": "message.json-query",
  "path": "",
  "position": 1,
  "raw": {
    "hint_template": "Use the WITH WRAPPER clause to wrap SQL/JSON items into an array.",
    "id": "message.json-query",
    "primary_template": "JSON path expression in JSON_QUERY must return single item when no wrapper is requested",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.cardinality"
    ],
    "sqlstate": "22034"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.cardinality"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "JSON path expression in JSON_QUERY must return single item when no wrapper is requested",
      "position": 0,
      "role": "",
      "template": "JSON path expression in JSON_QUERY must return single item when no wrapper is requested"
    },
    {
      "kind": "hint",
      "literal": "Use the WITH WRAPPER clause to wrap SQL/JSON items into an array.",
      "position": 1,
      "role": "",
      "template": "Use the WITH WRAPPER clause to wrap SQL/JSON items into an array."
    }
  ]
}

messages · message.json-value

{
  "limits": "",
  "message_id": "message.json-value",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.json-value",
    "primary_template": "JSON path expression in JSON_VALUE must return single scalar item",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.cardinality"
    ],
    "sqlstate": "22034"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.cardinality"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "JSON path expression in JSON_VALUE must return single scalar item",
      "position": 0,
      "role": "",
      "template": "JSON path expression in JSON_VALUE must return single scalar item"
    }
  ]
}

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

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

sources · src.jsonpath.cardinality

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

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:00c46b2af84dfc515da2ba5cc0c1864d9c90fc7b3ab0f2a6b9eb20ca49e73b1a

Text language: en · english-manuals:00c46b2af84dfc515da2ba5cc0c1864d9c90fc7b3ab0f2a6b9eb20ca49e73b1a