Incident brief
JSON_VALUE must return a single scalar
JSON_VALUE must resolve to a single scalar; a path that returns an array, object, or multiple items raises this data exception, use JSON_QUERY for non-scalars.
What lands in your log
ERROR: JSON path expression in JSON_VALUE must return single scalar item
In 10 seconds
- What triggers it
- Call JSON_VALUE(doc, path) where the path returns an array, object, or multiple items rather than one scalar.
- Fix
- Point the path at a single scalar (an element like $[0] rather than the whole array).
- Proof
- Reproduced on PostgreSQL 18.4 → A single SELECT reproduces SQLSTATE 2203F; a non-scalar path result is rejected by JSON_VALUE.
Fix
What to do right now
Application-level steps for this error.
- Point the path at a single scalar (an element like $[0] rather than the whole array).
- Use JSON_QUERY instead of JSON_VALUE when you intend to return an array or object.
-- PostgreSQL 17+: address one scalar item.
SELECT JSON_VALUE('[1,2]'::jsonb, '$[0]' RETURNING int ERROR ON ERROR) AS one_value;For this error
See this error live on the server
Run these against the affected instance to confirm the diagnosis before you act.
JSON_VALUE must return a single scalar depends on SQL/JSON path cardinality. Check server version, then inspect the path with jsonb_path_query before choosing ON EMPTY/ON ERROR behavior.
SQL/JSON feature version
JSON_VALUE syntax is version-dependent; confirm the actual server before replaying documentation examples.
SELECT current_setting('server_version') AS server_version,
current_setting('server_version_num') AS server_version_num;Path result cardinality
Replace document/path with the failing values; this shows zero, one, or many items without forcing JSON_VALUE scalar semantics.
SELECT value
FROM jsonb_path_query(<json_document>::jsonb, <jsonpath_literal>) AS value;Why it happens
What PostgreSQL is telling you
The mechanism behind the error, grounded in the official manual, not paraphrased.
PostgreSQL 18 Documentation, Appendix A. PostgreSQL Error Codes (Table A.1, Class 22, Data Exception)
2203F → sql_json_scalar_requiredRead the full section on postgresql.org →
Returning a non-scalar from JSON_VALUE
JSON_VALUE must yield exactly one scalar, so a path returning an array raises 'JSON path expression in JSON_VALUE must return single scalar item'.The session continues normally
This was a standalone JSON_VALUE call, not part of a transaction, so the session needs no cleanup before its next query.Reproduce & verify
A real, single-session PostgreSQL reproduction
A literal transcript of SQL run against a live PostgreSQL instance in an isolated lab. The commands below are exactly what was executed.
- 1Call JSON_VALUE(doc, path) where the path returns an array, object, or multiple items rather than one scalar.
- 2PostgreSQL evaluates the path and finds the result is not a single scalar value.
- 3The statement aborts with SQLSTATE 2203F.
A query used JSON_VALUE to read what turned out to be an array field, and it failed until the path selected a single element.
-- The error is self-contained in one statement; no schema is required.
SELECT 'no schema needed' AS setup_note;SELECT JSON_VALUE('[1,2]'::jsonb, '$' RETURNING int ERROR ON ERROR);SELECT 'ok' AS session_after_error;What PostgreSQL actually returned
setup_note
------------------
no schema needed
(1 row)ERROR: JSON path expression in JSON_VALUE must return single scalar item session_after_error
---------------------
ok
(1 row)The same function returns a value once the path selects a single scalar.
Without this
Before: a non-scalar path aborts
With this, tested
After: '$[0]' returns a scalar
- A second operational test: exact SQL, raw output, measured result, and engineer notes
Card required. Cancel before day 7 and you are not charged.
Connected
Everything this error touches
Every page this SQLSTATE connects to: the concept that explains it, the runbooks that fix it, the parameters you tune to prevent it, and the sibling errors it travels with. All real cross-references. Jump straight in, or open the full interactive map.
Related errors
Verification
- Last verified
- 2026-07-24 (isolated lab, PostgreSQL 18.4)
- Verification scope
- Verified against PostgreSQL 18.4 in an isolated lab environment
- Audit status
- reviewed
Went further?
Pro unlocks the second lab proof
Free page stops the bleeding. Pro adds the operational test, SQLSTATE audit, and deeper evidence, same error, more certainty.