# 2203C — sql_json_object_not_found

> PostgreSQL SQLSTATE 2203C 的来源与诊断参考。
---

# 2203C

## 速览 {#at-a-glance}
只接受对象的 JSON 路径访问器或 `.keyvalue()` 方法收到了非对象项。通配成员访问和对象键值展开使用这个结构检查条件。

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

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `2203C` |
| 条件名 | `sql_json_object_not_found` |
| 状态 | `有效` |
| 已知存在于 | `12.0` |
| 锁定快照 | `12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| 宏 | `ERRCODE_SQL_JSON_OBJECT_NOT_FOUND` |
| 别名 | `—` |

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

## 报文 {#messages}
代表性首要报文如下：

| 触发条件 | 首要报文 |
| --- | --- |
| 通配成员访问器收到非对象 | `jsonpath wildcard member accessor can only be applied to an object` |
| `.keyvalue()` 收到非对象 | `jsonpath item method .%s() can only be applied to an object` |

## 含义 {#meaning}
通配成员分支要求 JSON 对象；当 `jspIgnoreStructuralErrors` 为 true 时，非对象结构不匹配可以被忽略，lax 模式也可能先自动解包数组。`.keyvalue()` 同样可能先自动解包数组，但随后直接要求对象容器；它的非对象检查通过 `RETURN_ERROR` 执行，抛错还是返回 `jperError` 由 `jspThrowErrors` 决定，而该上下文取决于调用方的 silent 或 ON ERROR 处理。lax 本身不会抑制 `.keyvalue()` 的直接检查。具名成员缺键属于 2203A，只接受数组的访问属于 22039。

## 诊断 {#diagnosis}
根据首要报文确认是通配访问器还是项方法，再检查当前项类型。区分对象接收项缺少具名键，与标量/数组接收项不能进行对象展开。将 lax 自动解包和结构错误处理纳入判断，不要直接把结果归为成员缺失。

## 处理 {#response}
让路径选出对象、规范化输入形状，或在调用只接受对象的操作前显式分支。对通配访问，只有当业务确实要丢弃非对象分支时才使用 lax 结构抑制；对 `.keyvalue()`，lax 只能先解包数组，剩余的非对象仍按直接的抛错/silent/ON ERROR 路径处理，不要假设 lax 会忽略它。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的动作。

## 版本 {#versions}
锁定目录从 12.0 起记录该条件；固定的只接受对象的访问器和 `.keyvalue()` 检查条件来自 PostgreSQL 18.6。本页未声称有自然运行观察。

## 相关 {#related}
[`22039`](../22039/)、[`2203A`](../2203a/)、[`22037`](../22037/)

## 来源 {#sources}
通配成员检查条件见 [`jsonpath_exec.c#L852-874`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L852)，`.keyvalue()` 对象容器检查见 [`#L2806-2828`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L2806)。共享 strict/lax 与抛出/返回宏见 [`jsonpath_exec.c#L235-249`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L235)。结构化[证据记录](../../data/evidence/2203c.json)绑定两条只接受对象的首要报文；本页未运行自然案例。