22016 — invalid_argument_for_nth_value_function

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

English manual coverage begins with PostgreSQL 8.1. Source history and runtime observations have their own recorded version boundaries.

Reading PG 18·Select a recorded version

8.4 9.0 9.1 9.2 9.3 9.4 9.5 9.6 10 11 12 13 14 15 16 17 18 19 20

aliases: Unknown
class name: Data Exception
condition name: invalid_argument_for_nth_value_function
lang: en
sqlstate: 22016

Definition PG 18

At a glance {#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 {#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 {#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 {#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 {#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 {#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 {#related}

22014, 22013

Sources {#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.

Compare versions

SQLSTATE evidence and recorded runtime versions

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read the fixed errcodes row and macro.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "22016 is invalid_argument_for_nth_value_function in SQLSTATE Class 22."
}

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "",
  "method": "Read the complete ordinal check, frame lookup, and NULL result path.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.nth-value.18.6"
  ],
  "statement": "window_nth_value returns NULL for a NULL ordinal, raises 22016 for a non-positive ordinal, and returns NULL when a valid positive ordinal selects no row in the current frame or a NULL value."
}

claims · history

{
  "claim_id": "history",
  "limits": "",
  "method": "Use catalogue presence and history boundaries.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records 22016 from 8.4.0 without proving an exact implementation introduction date."
}

messages · message.nonpositive-ordinal

{
  "limits": "",
  "message_id": "message.nonpositive-ordinal",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.nonpositive-ordinal",
    "primary_template": "argument of nth_value must be greater than zero",
    "severity_source": "ERROR",
    "sources": [
      "src.nth-value.18.6"
    ],
    "sqlstate": "22016"
  },
  "severity": "ERROR",
  "sources": [
    "src.nth-value.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "argument of nth_value must be greater than zero",
      "position": 0,
      "role": "",
      "template": "argument of nth_value must be greater than zero"
    }
  ]
}

sources · src.errcodes.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/errcodes.txt",
  "position": 0,
  "sha256": "6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba",
  "source_id": "src.errcodes.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L186"
}

sources · src.nth-value.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/windowfuncs.c",
  "position": 1,
  "sha256": "49214f9325dcdd73728d08574b0b6843e90822a18bdaf6b0d49139b1eaae6b63",
  "source_id": "src.nth-value.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/windowfuncs.c#L686-715"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:365850348911b2a708ee5835786ef8f5690bfaa8c9cfa8faeabbee6095b64d12

Text language: en · english-manuals:365850348911b2a708ee5835786ef8f5690bfaa8c9cfa8faeabbee6095b64d12