XX002 — index_corrupted

Source-backed full reference for PostgreSQL SQLSTATE XX002.

XX002

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.

Field	Value
SQLSTATE	`XX002`
Condition	`index_corrupted`
Status	`active`
Known present by	`7.4`
Locked snapshots	`9.0.23, 9.1.24, 9.2.24, 9.3.25, 9.4.26, 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_INDEX_CORRUPTED`
Aliases	`—`

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

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

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

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

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.

XX001, 58030, 54011