↑↓ 选择↵ 打开⌫ 切换范围完整搜索

PG.CENTER 连接 PostgreSQL 文档、百科与生态知识。由 Pigsty 维护。

Wiki / SQLSTATE

XX002 — index_corrupted

索引结构失败，如页面头部或元数据不合法。

英文手册覆盖始于 PostgreSQL 8.1. 来源历史与运行验证各自保留独立版本边界。

当前阅读 PG 18·选择有来源记录的版本

8.18.28.38.49.09.19.29.39.49.59.61011121314151617181920
aliases
未知
class name
Internal Error
condition name
index_corrupted
lang
en
sqlstate
XX002

版本定义 PG 18

XX002

速览 {#at-a-glance}

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

含义 {#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、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

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

比较版本

SQLSTATE 证据与已记录的运行版本

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

来源引用

完整定义与证据 JSON

定义来源

center · PostgreSQL 18 · english-manuals:ba8df1cb295ade47da62c513d3253636dd0429fb2f5a48633be4c79a4612f952

正文语言: zh-Hans · english-manuals:ba8df1cb295ade47da62c513d3253636dd0429fb2f5a48633be4c79a4612f952