# 22014 — invalid_argument_for_ntile_function

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

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

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

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `22014` |
| 条件名 | `invalid_argument_for_ntile_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_NTILE` |
| 别名 | `—` |

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

## 含义 {#meaning}
当 `context->ntile` 仍为零、尚未成功初始化时，`window_ntile` 才会计算桶参数。参数为 NULL 时先返回 NULL，也不会设置这个状态，因此后续行可能再次计算参数；小于等于零时抛出 `22014`，正数则初始化状态并在后续行复用。空输入没有可供窗口函数计算的行，不属于这个错误。

## 诊断 {#diagnosis}
检查受影响分区中 `ntile` 参数的解析值，区分三种情况：正数、NULL 和非正数。对实际求值的行，NULL 参数会给出 NULL；空分区则完全没有结果。二者都不应归为非正参数错误。

## 处理 {#response}
检查提供参数的表达式后传入正整数桶数量。只有桶策略本来就允许时，才使用 `COALESCE` 或其他回退值。固定 guard 抛出 `ERROR`；显式事务需先回滚或回到已有保存点再重试，自动提交只重试修正后的语句。

## 报文 {#messages}
- Primary，`ERROR`：`argument of ntile must be greater than zero`。
- 固定 guard 没有附加 DETAIL 或 HINT。

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

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

## 来源 {#sources}
[`src/backend/utils/adt/windowfuncs.c#L411-L475`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/windowfuncs.c#L411-L475) 展示分区行数、NULL 提前返回、正数 guard 和桶计算。运行核验为 `not_run`；上述源码证据不是运行观察。结构化[证据记录](../../data/evidence/22014.json)保留 primary 和范围。