2203F
Read PG 18 manual ↗sql_json_scalar_required
- SQLSTATE
- 2203F
- Condition name
- sql_json_scalar_required
- Class
- Data Exception
- Source macro
- ERRCODE_SQL_JSON_SCALAR_REQUIRED
- Evidence
- Source path confirmed
English SQLSTATE atlas: authored explanations and source/runtime evidence are separate from the manual definitions. View source ↗
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
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.
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.
Source evidence
Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.
2203F is sql_json_scalar_required in SQLSTATE Class 22.
Method: Read fixed definition.
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.
Method: Read the complete JsonPathValue empty, multiple-item, scalar-type, and error-pointer branches.
Limits: Source confirmation is not a natural runtime observation.
The locked catalogue records 2203F from 12.0 without proving exact implementation introduction.
Method: Use catalogue boundary.
- src/backend/utils/errcodes.txt · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7 - src/backend/utils/adt/jsonpath_exec.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7
Message templates
ERROR · message.scalar-column
Primary
JSON path expression for column "%s" must return single scalar item
ERROR · message.scalar-no-column
Primary
JSON path expression in JSON_VALUE must return single scalar item
Reproduction & repair cases
No reproduction case is attached to this condition.
Recorded runtime evidence
No runtime observation is attached to this entry.
Version history 1
- PG 11 → 12added
Definition snapshot: english-manuals:fd5581186df9bf1430c0b32a16d… · English manual source