XX002 — index_corrupted

XX002 reports an index-structure failure. The fixed sources are method-specific: BRIN checks a range-map pointer, while GiST and hash check page headers, special areas, and method-specific metadata.

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: Internal Error
condition name: index_corrupted
lang: en
sqlstate: XX002

Definition PG 18

XX002

At a glance {#at-a-glance}

XX002 reports an index-structure failure. The fixed sources are method-specific: BRIN checks a range-map pointer, while GiST and hash check page headers, special areas, and method-specific metadata.

Meaning {#meaning}

The BRIN revmap path raises XX002 when a range-map item points past the regular page or to an unused item. GiST and hash page-check functions reject an unexpected zero page or an invalid special area; hash also checks that the page type, magic, and version match the hash access method. These checks can fire during normal index access or validation and do not by themselves prove that the heap is sound.

Messages {#messages}

ERROR, SQLSTATE XX002: corrupted BRIN index: inconsistent range map.
ERROR, SQLSTATE XX002 (GiST): index "%s" contains unexpected zero page at block %u; hint Please REINDEX it.
ERROR, SQLSTATE XX002 (GiST or hash): index "%s" contains corrupted page at block %u; hint Please REINDEX it.
ERROR, SQLSTATE XX002 (hash): index "%s" is not a hash index.
ERROR, SQLSTATE XX002 (hash): index "%s" has wrong hash version; hint Please REINDEX it.

The BRIN branch has no fixed REINDEX hint in the cited source. The same message may be reached from more than one page-check guard, so retain the access method and block.

Diagnosis {#diagnosis}

Record access method, index OID/name, block, page header/special-area detail, primary/detail/hint, and the first query, check, or maintenance operation that observed the failure. Compare the index with the heap, amcheck output, checksums, replicas, and storage history. A repeated failure after a rebuild suggests an underlying heap, storage, or software problem rather than a one-off index page.

Response {#response}

For an ERROR in an explicit transaction, roll back or return to an existing savepoint before issuing more SQL. Preserve the original index and evidence before repair. If comparison establishes that corruption is index-local and the heap is trusted, rebuild the affected index with the access method's documented maintenance procedure; the GiST/hash hints explicitly say REINDEX it, while the BRIN message does not prescribe a repair. Verify the rebuilt index and dependent constraints. REINDEX cannot repair heap/TOAST/storage corruption, and rebuilding a corrupted index over bad heap data can reproduce the problem; if the backend was terminated by a separate FATAL, recover and use a new connection.

Versions {#versions}

The locked catalogue records this condition from 7.4; fixed BRIN, GiST, and hash source coverage is PostgreSQL 18.6. No index or corruption runtime was induced for this source-only page.

Related {#related}

XX001, 58030, 54011

Sources {#sources}

src/backend/access/brin/brin_revmap.c#L381-L389

src/backend/access/gist/gistutil.c#L796-L812

src/backend/access/hash/hashutil.c#L221-L270

The structured evidence record records access-method-specific message guards, hints, and the source/runtime boundary.

Compare versions

SQLSTATE evidence and recorded runtime versions

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read locked definition snapshot.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "XX002 is index_corrupted in SQLSTATE Class XX."
}

claims · resolved-paths

{
  "claim_id": "resolved-paths",
  "limits": "Source confirmation is not natural runtime and does not establish that corruption is index-local in an incident.",
  "method": "Read complete fixed access-method guards.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.0",
    "src.path.1",
    "src.path.2"
  ],
  "statement": "Fixed source paths cover BRIN range-map validation, GiST page checks, and hash page/type/version checks with method-specific REINDEX hints."
}

claims · history

{
  "claim_id": "history",
  "limits": "",
  "method": "Use locked catalogue boundary.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records XX002 from 7.4; it does not prove the exact introduction rationale."
}

messages · message.0

{
  "limits": "",
  "message_id": "message.0",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.0",
    "primary_template": "corrupted BRIN index: inconsistent range map",
    "severity_source": "ERROR",
    "sources": [
      "src.path.0"
    ],
    "sqlstate": "XX002"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.0"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "corrupted BRIN index: inconsistent range map",
      "position": 0,
      "role": "",
      "template": "corrupted BRIN index: inconsistent range map"
    }
  ]
}

messages · message.1

{
  "limits": "",
  "message_id": "message.1",
  "path": "",
  "position": 1,
  "raw": {
    "hint_template": "Please REINDEX it.",
    "id": "message.1",
    "primary_template": "index \"%s\" contains unexpected zero page at block %u",
    "severity_source": "ERROR",
    "sources": [
      "src.path.1"
    ],
    "sqlstate": "XX002"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.1"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "index \" \" contains unexpected zero page at block",
      "position": 0,
      "role": "",
      "template": "index \"%s\" contains unexpected zero page at block %u"
    },
    {
      "kind": "hint",
      "literal": "Please REINDEX it.",
      "position": 1,
      "role": "",
      "template": "Please REINDEX it."
    }
  ]
}

messages · message.2

{
  "limits": "",
  "message_id": "message.2",
  "path": "",
  "position": 2,
  "raw": {
    "hint_template": "Please REINDEX it.",
    "id": "message.2",
    "primary_template": "index \"%s\" contains corrupted page at block %u",
    "severity_source": "ERROR",
    "sources": [
      "src.path.1",
      "src.path.2"
    ],
    "sqlstate": "XX002"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.1",
    "src.path.2"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "index \" \" contains corrupted page at block",
      "position": 0,
      "role": "",
      "template": "index \"%s\" contains corrupted page at block %u"
    },
    {
      "kind": "hint",
      "literal": "Please REINDEX it.",
      "position": 1,
      "role": "",
      "template": "Please REINDEX it."
    }
  ]
}

messages · message.3

{
  "limits": "",
  "message_id": "message.3",
  "path": "",
  "position": 3,
  "raw": {
    "id": "message.3",
    "primary_template": "index \"%s\" is not a hash index",
    "severity_source": "ERROR",
    "sources": [
      "src.path.2"
    ],
    "sqlstate": "XX002"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.2"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "index \" \" is not a hash index",
      "position": 0,
      "role": "",
      "template": "index \"%s\" is not a hash index"
    }
  ]
}

messages · message.4

{
  "limits": "",
  "message_id": "message.4",
  "path": "",
  "position": 4,
  "raw": {
    "hint_template": "Please REINDEX it.",
    "id": "message.4",
    "primary_template": "index \"%s\" has wrong hash version",
    "severity_source": "ERROR",
    "sources": [
      "src.path.2"
    ],
    "sqlstate": "XX002"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.2"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "index \" \" has wrong hash version",
      "position": 0,
      "role": "",
      "template": "index \"%s\" has wrong hash version"
    },
    {
      "kind": "hint",
      "literal": "Please REINDEX it.",
      "position": 1,
      "role": "",
      "template": "Please REINDEX it."
    }
  ]
}

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

sources · src.path.0

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/access/brin/brin_revmap.c",
  "position": 1,
  "sha256": "365bf30dcebf5923b8098206f303b05532dd3a0526f9316369b3465cd9d2a5da",
  "source_id": "src.path.0",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/access/brin/brin_revmap.c#L381"
}

sources · src.path.1

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/access/gist/gistutil.c",
  "position": 2,
  "sha256": "90fd8be8c4f101a1f4621026c1a452c13b82940c44e6172589e9421fbc87a243",
  "source_id": "src.path.1",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/access/gist/gistutil.c#L796"
}

sources · src.path.2

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/access/hash/hashutil.c",
  "position": 3,
  "sha256": "25c4945d8f26a3403968d19be8fc7870ec3ed504d4ade5bcddf73e5104542b19",
  "source_id": "src.path.2",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/access/hash/hashutil.c#L221"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:ba8df1cb295ade47da62c513d3253636dd0429fb2f5a48633be4c79a4612f952

Text language: en · english-manuals:ba8df1cb295ade47da62c513d3253636dd0429fb2f5a48633be4c79a4612f952