22016 — invalid_argument_for_nth_value_function

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.