22016

At a glance

nth_value received a non-positive ordinal. The fixed window-function path reports argument of nth_value must be greater than zero with SQLSTATE 22016.

Meaning

window_nth_value first reads the ordinal argument: NULL returns NULL, while an ordinal less than or equal to zero raises 22016. A positive ordinal is then converted to a zero-based frame offset. If that row is outside the current frame, or the selected value itself is NULL, the executor returns NULL; neither case is 22016.

Diagnosis

Check the evaluated ordinal, the window ordering, and the frame boundaries. Distinguish an invalid non-positive argument from a valid positive argument whose target row is not in the frame. A NULL ordinal is also a NULL result path, so do not turn it into this error merely because the result is NULL.

Response

Supply a positive ordinal when the function is meant to select a row, then adjust the ordering or frame only if the target row must be included. Preserve a NULL result when it represents a missing frame row or a NULL value. The non-positive guard raises ERROR; in an explicit transaction roll back or return to an existing savepoint before retrying, while autocommit can retry only the corrected statement.

Messages

• Primary, ERROR: argument of nth_value must be greater than zero.
• The non-positive-ordinal guard adds no DETAIL or HINT; out-of-frame and NULL-value paths return NULL instead.

Versions

The locked catalogue records this condition from 8.4.0; fixed source coverage is PostgreSQL 18.6. The cited behavior is the window-function implementation, not a general ordinal validator.

Related

22014, 22013

Sources

src/backend/utils/adt/windowfuncs.c#L686-L715 shows NULL handling, the positive-ordinal guard, the frame lookup, and the NULL return when no target row/value is available. Runtime verification is not_run; this source evidence is not a runtime observation. The structured evidence record retains the primary and scope.

Source evidence

Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.

• src/backend/utils/errcodes.txt · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/utils/adt/windowfuncs.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7

Message templates

argument of nth_value must be greater than zero

Reproduction & repair cases

No reproduction case is attached to this condition.

Recorded runtime evidence

No runtime observation is attached to this entry.