# XX002 — index_corrupted

> PostgreSQL SQLSTATE XX002 的源码核验与诊断参考。
---

# XX002

## 速览 {#at-a-glance}

`XX002` 报告索引结构失败。固定源码按索引访问方法区分：BRIN 检查范围映射指针，GiST 和 hash 检查页面头部、特殊区域以及方法特有的 metadata。

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

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `XX002` |
| 条件名 | `index_corrupted` |
| 状态 | `有效` |
| 已知存在于 | `7.4` |
| 锁定快照 | `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` |
| 宏 | `ERRCODE_INDEX_CORRUPTED` |
| 别名 | `—` |

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

## 含义 {#meaning}

BRIN revmap 路径在范围映射项指向普通页面之外或未使用项时报告 `XX002`。GiST 和 hash 页面检查会拒绝异常零页面或无效特殊区域；hash 还检查页面类型、magic 和 version 是否符合 hash 索引访问方法。这些检查可以在普通索引访问或校验时触发，不能单独证明堆完好。

## 消息 {#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 或 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.`

引用的 BRIN 分支没有固定 REINDEX 提示。同一消息可能由多个页面检查分支触发，因此应保留索引访问方法和数据块。

## 诊断 {#diagnosis}

记录索引访问方法、索引 OID/名称、数据块、页面头部/特殊区域详细信息、主消息/详细信息/提示以及首次发现错误的查询、检查或维护操作。比较索引、堆、`amcheck` 输出、校验和、副本和存储历史。重建后立即再次损坏，通常提示堆、存储或软件问题，而非单个索引页面。

## 处理 {#response}

显式事务中的 `ERROR` 需要先回滚，或回到已有保存点，再发送 SQL。修复前保留原始索引和证据。只有比较确认损坏局限于索引且堆可信时，才按索引访问方法的维护流程重建；GiST/hash 提示明确写 `REINDEX it`，BRIN 消息本身没有指定修复。重建后验证索引和依赖约束。REINDEX 不能修复堆/TOAST/存储损坏，在坏堆上重建可能再次产生问题；若另有 FATAL 使后端终止，恢复后使用新连接。

## 版本 {#versions}

锁定目录从 7.4 记录此条件；固定 BRIN、GiST 和 hash 源码覆盖 PostgreSQL 18.6。本源码页没有诱发索引或损坏故障。

## 相关 {#related}

[`XX001`](../xx001/)、[`58030`](../58030/)、[`54011`](../54011/)

## 来源 {#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)

结构化[证据记录](../../data/evidence/xx002.json)保存索引访问方法特有的消息检查分支、提示和源码/运行边界。