SQLSTATE / Class 22 · Data Exception
22014
Read the PG 18 manualinvalid_argument_for_ntile_function
Reading PG 18current·documented in 19 of 22 versions, 8.4 to 20
- SQLSTATE
- 22014
- Condition name
- invalid_argument_for_ntile_function
- Class
- Data Exception
- Source macro
- ERRCODE_INVALID_ARGUMENT_FOR_NTILE
- Evidence
- Source path confirmed
English SQLSTATE atlas: authored explanations and source/runtime evidence are separate from the manual definitions. View source
At a glance
ntile received a non-positive bucket count. The fixed window-function path reports argument of ntile must be greater than zero with SQLSTATE 22014.
Meaning
While context->ntile is still zero, before a successful initialization, window_ntile evaluates the bucket argument. A NULL argument returns NULL before setting that state, so a later row may evaluate the argument again; a value less than or equal to zero raises 22014, while a positive count initializes the state and is reused for later rows. An empty input produces no window-function row to evaluate and is not this error.
Diagnosis
Inspect the resolved ntile argument for the affected partition and distinguish three cases: positive count, NULL count, and non-positive count. A NULL count gives a NULL result on rows that are evaluated; an empty partition gives no result at all. Neither should be reported as the non-positive-argument error.
Response
Pass a positive integer bucket count after checking the expression that supplies it. Use COALESCE or another fallback only when the resulting bucket policy is intentional. The fixed 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 ntile must be greater than zero. - The fixed guard adds no DETAIL or HINT.
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 argument validator.
Sources
src/backend/utils/adt/windowfuncs.c#L411-L475 shows the partition-row count, NULL early return, positive-count guard, and bucket calculation. 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.
22014 is invalid_argument_for_ntile_function in SQLSTATE Class 22.
Method: Read the fixed errcodes row and macro.
When ntile state is still uninitialized, the function evaluates the bucket argument; NULL returns before initialization, non-positive raises 22014, and a positive count initializes and is reused for later rows.
Method: Read the complete window_ntile initialization, NULL, guard, and distribution path.
Limits: An empty input has no window-function row to evaluate.
The locked catalogue records 22014 from 8.4.0 without proving an exact implementation introduction date.
Method: Use catalogue presence and history boundaries.
- src/backend/utils/errcodes.txt · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7 - src/backend/utils/adt/windowfuncs.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7
Message templates
ERROR · message.nonpositive-buckets
Primary
argument of ntile 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.
Version history 1
- 8.3 → 8.4 added
Definition snapshot: english-manuals:1d02a301edae7422387809250c4… · English manual source