# XX002 — index_corrupted

> Source-backed full reference for PostgreSQL SQLSTATE XX002.
---

# 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.

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| 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 | `—` |

<!-- source facts: data/errcodes/XX002.json -->
<!-- END SQLSTATE FACTS -->

## 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`](../xx001/), [`58030`](../58030/), [`54011`](../54011/)

## Sources {#sources}

[`src/backend/access/brin/brin_revmap.c#L381-L389`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/access/brin/brin_revmap.c#L381)

[`src/backend/access/gist/gistutil.c#L796-L812`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/access/gist/gistutil.c#L796)

[`src/backend/access/hash/hashutil.c#L221-L270`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/access/hash/hashutil.c#L221)

The structured [evidence record](../data/evidence/xx002.json) records access-method-specific message guards, hints, and the source/runtime boundary.