2203F — sql_json_scalar_required
2203F
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.
| 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 | — |
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
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
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
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
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
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.