2201G — invalid_argument_for_width_bucket_function

width_bucket validates its bucket count, NaN inputs, histogram bounds, and bound equality. The fixed numeric and float8 paths report distinct 2201G messages for non-positive count, NaN, non-finite bounds, and equal bounds.

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.1 8.2 8.3 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_width_bucket_function
lang: en
sqlstate: 2201G

Definition PG 18

2201G

At a glance {#at-a-glance}

width_bucket validates its bucket count, NaN inputs, histogram bounds, and bound equality. The fixed numeric and float8 paths report distinct 2201G messages for non-positive count, NaN, non-finite bounds, and equal bounds.

Representative messages {#messages}

The fixed guards use these primary texts:

| Guard | Primary | | --- | --- | | non-positive count | count must be greater than zero | | any NaN operand or bound | operand, lower bound, and upper bound cannot be NaN | | non-finite bound | lower and upper bounds must be finite | | equal bounds | lower bound cannot equal upper bound |

Meaning {#meaning}

For the numeric and float8 width_bucket(operand, bound1, bound2, count) signatures, count must be greater than zero; operand or either bound cannot be NaN; and both bounds must be finite and unequal. The implementation accepts either ascending or descending bounds, and an infinite operand is allowed even though an infinite bound is not. If a valid endpoint calculation overflows count + 1, the source reports 22003 instead.

Diagnosis {#diagnosis}

Use the function signature and the exact primary message to identify the offending argument. Check count, then distinguish NaN from infinity and distinguish the operand from the two bounds. Do not impose a lower-than-upper rule: descending bounds have their own valid bucket calculation. An equal pair is the specific ordering failure covered by 2201G.

Response {#response}

Correct the named count, operand, or bound while preserving the intended bucket direction. Keep both bounds finite and unequal, use a positive count, and handle an out-of-range result as the separate 22003 condition. If this ERROR occurred in an explicit transaction, roll back or roll back to the existing savepoint before retrying; autocommit can retry the corrected call.

Versions {#versions}

The locked catalogue records this condition from 8.0.0; the fixed source paths here are PostgreSQL 18.6. No natural runtime observation is claimed for this page.

Related {#related}

22003, 22012

Sources {#sources}

The complete representative guards are in src/backend/utils/adt/numeric.c#L1959-2045 and src/backend/utils/adt/float.c#L4060-4180. The structured evidence record retains all four primary templates and the bounded source scope; no natural runtime was run.

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": "2201G is invalid_argument_for_width_bucket_function in SQLSTATE Class 22"
}

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "Source confirmation is not a natural runtime observation.",
  "method": "Read complete source contexts for the representative guards.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.numeric.width_bucket",
    "src.float.width_bucket"
  ],
  "statement": "Fixed PostgreSQL 18.6 numeric and float8 width_bucket paths bind count, NaN, finite-bound, unequal-bound, ascending, descending, and operand-infinity behavior."
}

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 2201G from 8.0.0 without proving an exact implementation introduction date."
}

claims · neighbor-22003

{
  "claim_id": "neighbor-22003",
  "limits": "",
  "method": "Read the result conversion/overflow branch, not the 2201G guards.",
  "position": 3,
  "runtime": [],
  "sources": [
    "src.numeric.width_bucket",
    "src.float.width_bucket"
  ],
  "statement": "Valid endpoint arithmetic can raise the distinct 22003 integer-out-of-range condition when count plus one exceeds int4."
}

messages · message.count

{
  "limits": "",
  "message_id": "message.count",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.count",
    "primary_template": "count must be greater than zero",
    "severity_source": "ERROR",
    "sources": [
      "src.numeric.width_bucket",
      "src.float.width_bucket"
    ],
    "sqlstate": "2201G"
  },
  "severity": "ERROR",
  "sources": [
    "src.numeric.width_bucket",
    "src.float.width_bucket"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "count must be greater than zero",
      "position": 0,
      "role": "",
      "template": "count must be greater than zero"
    }
  ]
}

messages · message.nan

{
  "limits": "",
  "message_id": "message.nan",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.nan",
    "primary_template": "operand, lower bound, and upper bound cannot be NaN",
    "severity_source": "ERROR",
    "sources": [
      "src.numeric.width_bucket",
      "src.float.width_bucket"
    ],
    "sqlstate": "2201G"
  },
  "severity": "ERROR",
  "sources": [
    "src.numeric.width_bucket",
    "src.float.width_bucket"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "operand, lower bound, and upper bound cannot be NaN",
      "position": 0,
      "role": "",
      "template": "operand, lower bound, and upper bound cannot be NaN"
    }
  ]
}

messages · message.bounds-finite

{
  "limits": "",
  "message_id": "message.bounds-finite",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.bounds-finite",
    "primary_template": "lower and upper bounds must be finite",
    "severity_source": "ERROR",
    "sources": [
      "src.numeric.width_bucket",
      "src.float.width_bucket"
    ],
    "sqlstate": "2201G"
  },
  "severity": "ERROR",
  "sources": [
    "src.numeric.width_bucket",
    "src.float.width_bucket"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "lower and upper bounds must be finite",
      "position": 0,
      "role": "",
      "template": "lower and upper bounds must be finite"
    }
  ]
}

messages · message.bounds-equal

{
  "limits": "",
  "message_id": "message.bounds-equal",
  "path": "",
  "position": 3,
  "raw": {
    "id": "message.bounds-equal",
    "primary_template": "lower bound cannot equal upper bound",
    "severity_source": "ERROR",
    "sources": [
      "src.numeric.width_bucket",
      "src.float.width_bucket"
    ],
    "sqlstate": "2201G"
  },
  "severity": "ERROR",
  "sources": [
    "src.numeric.width_bucket",
    "src.float.width_bucket"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "lower bound cannot equal upper bound",
      "position": 0,
      "role": "",
      "template": "lower bound cannot equal upper bound"
    }
  ]
}

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#L177"
}

sources · src.numeric.width_bucket

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/numeric.c",
  "position": 1,
  "sha256": "6cde7cd60b3330b83be35d1f014045f5fb5fe737f3c5db4c8ed4080b99f2b666",
  "source_id": "src.numeric.width_bucket",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/numeric.c#L1959"
}

sources · src.float.width_bucket

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/float.c",
  "position": 2,
  "sha256": "58914ae93c06c281e581a4bb2dcf2280e4ae1619f3ceb8f801f50beca87eecd8",
  "source_id": "src.float.width_bucket",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/float.c#L4060"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:2fd7be36d15c6a7373c5bcec215a281b135b1a478b5cf7eeeca00bb15ec428ee

Text language: en · english-manuals:2fd7be36d15c6a7373c5bcec215a281b135b1a478b5cf7eeeca00bb15ec428ee