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.

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.

Related

XX001, 58030, 54011

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.

Source evidence

Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.

• src/backend/utils/errcodes.txt · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/access/brin/brin_revmap.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/access/gist/gistutil.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/access/hash/hashutil.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7

Message templates

corrupted BRIN index: inconsistent range map

index "%s" contains unexpected zero page at block %u

Please REINDEX it.

index "%s" contains corrupted page at block %u

Please REINDEX it.

index "%s" is not a hash index

index "%s" has wrong hash version

Please REINDEX it.

Reproduction & repair cases

No reproduction case is attached to this condition.

Recorded runtime evidence

No runtime observation is attached to this entry.