2203F — sql_json_scalar_required

A JSON_VALUE operation received one item, but that item was not a scalar. Multiple items are handled earlier as 22034; empty results are handled by the empty/ON EMPTY path.

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_scalar_required
lang: en
sqlstate: 2203F

Definition PG 18

2203F

At a glance {#at-a-glance}

A JSON_VALUE operation received one item, but that item was not a scalar. Multiple items are handled earlier as 22034; empty results are handled by the empty/ON EMPTY path.

Messages {#messages}

The fixed JSON_VALUE scalar guard uses these primary forms:

| Context | Primary | | --- | --- | | JSON_VALUE mapped to a named column | JSON path expression for column "%s" must return single scalar item | | Standalone JSON_VALUE | JSON path expression in JSON_VALUE must return single scalar item |

Meaning {#meaning}

JsonPathValue first executes the path and marks an empty result. More than one item is the separate 22034 cardinality branch. With exactly one item, it unwraps a scalar JSON container if needed and then requires a JSON scalar; an object or array reaches 2203F. When the caller supplies an error pointer for ON ERROR handling, the function sets the error flag and returns NULL rather than throwing. The ordinary ERROR path reports the column-aware or column-less primary shown above.

Diagnosis {#diagnosis}

Check the JSON_VALUE path result count and the selected item type. An empty result, several items, or a non-scalar single item has a different branch and response. Inspect the column mapping and ON EMPTY/ON ERROR clauses before changing the source JSON, and distinguish JSON_QUERY's wrapper semantics from JSON_VALUE's scalar requirement.

Response {#response}

Make the path resolve to one scalar, change the SQL/JSON operation when an object or array is intended, or configure the documented empty/error behavior for expected absence. Do not add a wrapper to JSON_VALUE to make a collection scalar. 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 JSON_VALUE cardinality and scalar checks are PostgreSQL 18.6. No natural runtime observation is claimed for this page.

Related {#related}

22034, 22035, 22036

Sources {#sources}

The complete JSON_VALUE empty, multiple-item, scalar, and ON ERROR pointer branches are jsonpath_exec.c#L3991-4067. The structured evidence record binds the 22034 boundary and both 2203F 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": "2203F is sql_json_scalar_required in SQLSTATE Class 22."
}

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "Source confirmation is not a natural runtime observation.",
  "method": "Read the complete JsonPathValue empty, multiple-item, scalar-type, and error-pointer branches.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.jsonpath.value-cardinality"
  ],
  "statement": "The fixed JSON_VALUE executor marks an empty result before cardinality checks, reports 22034 for more than one item, and then requires the single remaining item to be a JSON scalar; a non-scalar item reaches 2203F. When an error pointer is supplied for ON ERROR handling, the function sets the error flag and returns NULL instead of throwing; the ordinary path emits the column-aware or column-less primary."
}

claims · history

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

messages · message.scalar-column

{
  "limits": "",
  "message_id": "message.scalar-column",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.scalar-column",
    "primary_template": "JSON path expression for column \"%s\" must return single scalar item",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.value-cardinality"
    ],
    "sqlstate": "2203F"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.value-cardinality"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "JSON path expression for column \" \" must return single scalar item",
      "position": 0,
      "role": "",
      "template": "JSON path expression for column \"%s\" must return single scalar item"
    }
  ]
}

messages · message.scalar-no-column

{
  "limits": "",
  "message_id": "message.scalar-no-column",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.scalar-no-column",
    "primary_template": "JSON path expression in JSON_VALUE must return single scalar item",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.value-cardinality"
    ],
    "sqlstate": "2203F"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.value-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#L230"
}

sources · src.jsonpath.value-cardinality

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

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:f785a0bb8848c85bc5bd05f28f701eb7ba9abd7002c0fd32376d486d8243b326

Text language: en · english-manuals:f785a0bb8848c85bc5bd05f28f701eb7ba9abd7002c0fd32376d486d8243b326