# 22016 — invalid_argument_for_nth_value_function

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

## 速览 {#at-a-glance}
`nth_value` 收到非正的序号。固定窗口函数路径以 SQLSTATE `22016` 报告 `argument of nth_value must be greater than zero`。

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

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `22016` |
| 条件名 | `invalid_argument_for_nth_value_function` |
| 状态 | `有效` |
| 已知存在于 | `8.4.0` |
| 锁定快照 | `9.0.23, 9.1.24, 9.2.24, 9.3.25, 9.4.26, 9.5.25, 9.6.24, 10.23, 11.22, 12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| 宏 | `ERRCODE_INVALID_ARGUMENT_FOR_NTH_VALUE` |
| 别名 | `—` |

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

## 含义 {#meaning}
`window_nth_value` 先读取序号参数：NULL 返回 NULL，小于等于零才抛出 `22016`。正序号随后转换为从帧头开始的零基偏移。如果目标行不在当前帧内，或选中的值本身为 NULL，执行器返回 NULL；这两种情况都不是 `22016`。

## 诊断 {#diagnosis}
检查序号实际值、窗口排序和帧边界。区分无效的非正参数与合法正参数但目标行不在帧内的情况。NULL 序号也是 NULL 结果路径，因此不能仅因结果为 NULL 就归为本码。

## 处理 {#response}
如果函数确实要选取某行，传入正序号；只有必须包含目标行时才调整排序或帧。若 NULL 表示帧中没有目标行或目标值本来为 NULL，应保留这个结果。非正 guard 抛出 `ERROR`；显式事务需先回滚或回到已有保存点再重试，自动提交只重试修正后的语句。

## 报文 {#messages}
- Primary，`ERROR`：`argument of nth_value must be greater than zero`。
- 非正序号 guard 没有附加 DETAIL 或 HINT；超出帧和 NULL 值路径改为返回 NULL。

## 版本 {#versions}
锁定目录从 8.4.0 起记录该条件；固定源码覆盖 PostgreSQL 18.6。引用的是窗口函数实现，不是一般序号校验器。

## 相关 {#related}
[`22014`](../22014/)、[`22013`](../22013/)

## 来源 {#sources}
[`src/backend/utils/adt/windowfuncs.c#L686-L715`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/windowfuncs.c#L686-L715) 展示 NULL 处理、正序号 guard、帧查找，以及没有目标行/值时返回 NULL。运行核验为 `not_run`；上述源码证据不是运行观察。结构化[证据记录](../../data/evidence/22016.json)保留 primary 和范围。