# 2203F — sql_json_scalar_required

> Source-backed reference for PostgreSQL SQLSTATE 2203F.
---

# 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.

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| Field | Value |
| --- | --- |
| SQLSTATE | `2203F` |
| Condition | `sql_json_scalar_required` |
| Status | `active` |
| Known present by | `12.0` |
| Locked snapshots | `12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| Macros | `ERRCODE_SQL_JSON_SCALAR_REQUIRED` |
| Aliases | `—` |

<!-- source facts: data/errcodes/2203F.json -->
<!-- END SQLSTATE FACTS -->

## 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`](../22034/), [`22035`](../22035/), [`22036`](../22036/)

## Sources {#sources}
The complete JSON_VALUE empty, multiple-item, scalar, and ON ERROR pointer branches are [`jsonpath_exec.c#L3991-4067`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L3991). The structured [evidence record](../data/evidence/2203f.json) binds the 22034 boundary and both 2203F primaries; no natural runtime was run.