2202H — invalid_tablesample_argument
2202H
At a glance
A TABLESAMPLE method received an invalid argument. Fixed core and contrib methods reject out-of-range percentages or negative sample sizes with method-specific messages.
| Field | Value |
|---|---|
| SQLSTATE | 2202H |
| Condition | invalid_tablesample_argument |
| Status | active |
| Known present by | 9.5.0 |
| Locked snapshots | 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 |
| Macros | ERRCODE_INVALID_TABLESAMPLE_ARGUMENT |
| Aliases | — |
Messages
The fixed executor and sampling methods use these primary texts:
| Owner / guard | Primary |
|---|---|
| NULL method argument | TABLESAMPLE parameter cannot be null |
| Bernoulli/system percentage, including NaN | sample percentage must be between 0 and 100 |
system_rows negative size |
sample size must not be negative |
system_time negative or NaN time |
sample collection time must not be negative |
Meaning
2202H is a method-argument code, not one universal TABLESAMPLE range. The executor rejects a NULL method argument before calling the method. Core Bernoulli and system methods accept percentages from 0 through 100 inclusive and reject NaN. The system_rows contrib method rejects only a negative requested row count, so zero is allowed; system_time rejects negative or NaN collection time, so zero is allowed; the shown guard does not impose a finite upper bound, and positive Infinity is not rejected by that comparison itself. REPEATABLE NULL is the separate 2202G branch, and other sampling extensions may define their own argument guards.
Diagnosis
Identify the sampling method and parameter position before changing the value. A NULL method argument points to the executor guard; a Bernoulli/system percentage outside 0..100 or NaN points to the core method; negative system_rows size and negative/NaN system_time are contrib-specific; positive Infinity is not classified by that shown guard. Read the primary text to distinguish these from a NULL REPEATABLE seed (2202G).
Response
Use a non-NULL method argument, a finite percentage in the inclusive 0..100 range, a non-negative row count, or a non-negative finite collection time according to the selected method. Do not repair a 2202G repeat-seed error by changing the method percentage. If an ERROR occurred in an explicit transaction, roll back or roll back to the existing savepoint before retrying; autocommit can retry the corrected statement.
Versions
The locked catalogue records this condition from 9.5.0; the fixed core and contrib source paths here are PostgreSQL 18.6. No natural runtime observation is claimed for this page.
Related
Sources
The executor NULL guard is src/backend/executor/nodeSamplescan.c#L232-245. Core percentage guards are src/backend/access/tablesample/bernoulli.c#L137-149 and src/backend/access/tablesample/system.c#L140-152. Contrib bounds are contrib/tsm_system_rows/tsm_system_rows.c#L178-187 and contrib/tsm_system_time/tsm_system_time.c#L193-203. The structured evidence record retains the method-specific messages and limits; no natural runtime was run.