# 22039 — sql_json_array_not_found

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

# 22039

## 速览 {#at-a-glance}
只接受数组的 JSON 路径访问器或项方法在没有允许自动包装或结构错误抑制时收到了非数组项。固定的通配数组、索引数组和 `.size()` 路径分别有数组类型首要报文；越界下标属于 22033。

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

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

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

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

| 触发条件 | 首要报文 |
| --- | --- |
| 通配数组访问器收到非数组 | `jsonpath wildcard array accessor can only be applied to an array` |
| 索引数组访问器收到非数组 | `jsonpath array accessor can only be applied to an array` |
| `.size()` 在不允许自动包装时收到非数组 | `jsonpath item method .%s() can only be applied to an array` |

## 含义 {#meaning}
`jpiAnyArray` 通配入口、`jpiIndexArray` 索引入口和 `.size()` 项方法入口，在 lax 模式启用 `jspAutoWrap(cxt)` 时都可以把非数组项自动包装。未允许自动包装时，`jspIgnoreStructuralErrors` 可以抑制结构不匹配；两者都不适用时，相应的只接受数组分支才报告 22039。有效数组却使用越界下标会进入独立的 22033 下标检查条件，因此 22039 不表示空数组或下标越界。

## 诊断 {#diagnosis}
根据首要报文确认具体访问器或方法，并检查它前一步收到的项。区分标量/对象输入与有效数组的越界索引，同时确认 SQL/JSON 路径模式是否启用了 lax 结构错误处理或自动包装/解包。

## 处理 {#response}
让路径选出数组、规范化输入形状，或改用适用于标量的操作。如果文档可能同时出现标量和数组，应显式处理这两种分支，不要依赖结构不匹配变成空结果。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的动作。

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

## 相关 {#related}
[`2203C`](../2203c/)、[`2203A`](../2203a/)、[`22033`](../22033/)

## 来源 {#sources}
通配、索引和自动包装检查见 [`jsonpath_exec.c#L836-979`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L836)；`.size()` 数组检查见 [`#L1101-1117`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L1101)。strict/lax 结构处理和抛出/返回宏见 [`#L235-249`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L235)。结构化[证据记录](../../data/evidence/22039.json)绑定准确的数组报文和 22033 边界；本页未运行自然案例。