XX001 — data_corrupted

XX001 reports an integrity invariant failure. The fixed sources cover corrupted PGLZ TOAST data, impossible MultiXact/XID freeze state in heap processing, and an amcheck B-tree check that can reveal a heap/HOT-chain problem behind an apparent index mismatch.

English manual coverage begins with PostgreSQL 8.1. Source history and runtime observations have their own recorded version boundaries.

Reading PG 18·Select a recorded version

8.1 8.2 8.3 8.4 9.0 9.1 9.2 9.3 9.4 9.5 9.6 10 11 12 13 14 15 16 17 18 19 20

aliases: Unknown
class name: Internal Error
condition name: data_corrupted
lang: en
sqlstate: XX001

Definition PG 18

XX001

At a glance {#at-a-glance}

XX001 reports an integrity invariant failure. The fixed sources cover corrupted PGLZ TOAST data, impossible MultiXact/XID freeze state in heap processing, and an amcheck B-tree check that can reveal a heap/HOT-chain problem behind an apparent index mismatch.

Meaning {#meaning}

The TOAST decompressor raises ERRCODE_DATA_CORRUPTED when PGLZ cannot decode the stored compressed datum. Heap freezing raises the same code when a MultiXact precedes relminmxid, remains running before the freeze cutoff, or carries an update XID before relfrozenxid or the removable cutoff. These are consistency checks on stored data and transaction metadata, not invalid user input.

The amcheck heapallindexed callback reports a heap tuple lacking its matching index tuple. Its source comments warn that an apparent index-scan problem can still be heap corruption, a bad HOT-safety decision, or another underlying fault; the optional hint only asks for a stronger verification call.

Messages {#messages}

ERROR, SQLSTATE XX001: compressed pglz data is corrupt.
ERROR, SQLSTATE XX001: found multixact %u from before relminmxid %u.
ERROR, SQLSTATE XX001: multixact %u from before multi freeze cutoff %u found to be still running.
ERROR, SQLSTATE XX001: multixact %u contains update XID %u from before relfrozenxid %u.
ERROR, SQLSTATE XX001: multixact %u contains committed update XID %u from before removable cutoff %u.
ERROR, SQLSTATE XX001: heap tuple (%u,%u) from table "%s" lacks matching index tuple within index "%s".
- When the check was entered through bt_index_check (which takes AccessShareLock and passes readonly=false to the callback), hint: Retrying verification using the function bt_index_parent_check() might provide a more specific error. The bt_index_parent_check entry point takes ShareLock, passes readonly=true, and does not append this hint. This internal verification mode is unrelated to the SQL transaction's transaction_read_only setting.

Diagnosis {#diagnosis}

Preserve the exact message and identifiers, relation/index names, block and page context, checksum and replica comparison, server log, and the first operation that observed the invariant. For TOAST, identify the owning table and compressed datum path. For heap messages, inspect relfrozenxid/relminmxid and MultiXact history without manually editing system catalogs. For amcheck, record whether the call used bt_index_check/AccessShareLock or bt_index_parent_check/ShareLock, and whether the hint was present; do not assume the index is the root cause.

Response {#response}

Treat these as integrity incidents. In an explicit transaction, an ERROR requires ROLLBACK or ROLLBACK TO an existing savepoint before more SQL, but rollback does not repair the stored object. Compare trusted backups, replicas, checksums and storage history using a read-only procedure; then restore or rebuild the affected table/TOAST data according to the incident plan. A REINDEX may be appropriate only after evidence shows corruption is index-local; it is not a generic repair for heap, TOAST, XID, or MultiXact invariants. If a separate FATAL or process termination occurred, use a new connection after recovery; do not induce corruption to test this code.

Versions {#versions}

The locked catalogue records this condition from 7.4; fixed TOAST, heap, and amcheck source coverage is PostgreSQL 18.6. No corruption or crash runtime was run for this source-only page.

Related {#related}

XX002, 58030, 72000

Sources {#sources}

src/backend/access/common/toast_compression.c#L90-L100

src/backend/access/heap/heapam.c#L6983-L7042

contrib/amcheck/verify_nbtree.c#L2760-L2818

contrib/amcheck/verify_nbtree.c#L252-L305

contrib/amcheck/verify_common.c#L60-L149

The structured evidence record records the integrity message groups, conditional hint, and source/runtime boundary.

Compare versions

SQLSTATE evidence and recorded runtime versions

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read locked definition snapshot.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "XX001 is data_corrupted in SQLSTATE Class XX."
}

claims · resolved-paths

{
  "claim_id": "resolved-paths",
  "limits": "Source confirmation is not natural runtime and does not identify a particular incident root cause.",
  "method": "Read complete fixed integrity-check contexts, amcheck entry points, and the lock-mode-to-readonly mapping.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.0",
    "src.path.1",
    "src.path.2",
    "src.path.3",
    "src.path.4"
  ],
  "statement": "Fixed source paths cover PGLZ decompression corruption, MultiXact/XID freeze invariants, and the amcheck heapallindexed mismatch; bt_index_check uses AccessShareLock, while bt_index_parent_check uses ShareLock and causes the callback readonly flag that suppresses the parent-check hint."
}

claims · history

{
  "claim_id": "history",
  "limits": "",
  "method": "Use locked catalogue boundary.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records XX001 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": "compressed pglz data is corrupt",
    "severity_source": "ERROR",
    "sources": [
      "src.path.0"
    ],
    "sqlstate": "XX001"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.0"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "compressed pglz data is corrupt",
      "position": 0,
      "role": "",
      "template": "compressed pglz data is corrupt"
    }
  ]
}

messages · message.1

{
  "limits": "",
  "message_id": "message.1",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.1",
    "primary_template": "found multixact %u from before relminmxid %u",
    "severity_source": "ERROR",
    "sources": [
      "src.path.1"
    ],
    "sqlstate": "XX001"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.1"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "found multixact from before relminmxid",
      "position": 0,
      "role": "",
      "template": "found multixact %u from before relminmxid %u"
    }
  ]
}

messages · message.2

{
  "limits": "",
  "message_id": "message.2",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.2",
    "primary_template": "multixact %u from before multi freeze cutoff %u found to be still running",
    "severity_source": "ERROR",
    "sources": [
      "src.path.1"
    ],
    "sqlstate": "XX001"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.1"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "multixact from before multi freeze cutoff found to be still running",
      "position": 0,
      "role": "",
      "template": "multixact %u from before multi freeze cutoff %u found to be still running"
    }
  ]
}

messages · message.3

{
  "limits": "",
  "message_id": "message.3",
  "path": "",
  "position": 3,
  "raw": {
    "id": "message.3",
    "primary_template": "multixact %u contains update XID %u from before relfrozenxid %u",
    "severity_source": "ERROR",
    "sources": [
      "src.path.1"
    ],
    "sqlstate": "XX001"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.1"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "multixact contains update XID from before relfrozenxid",
      "position": 0,
      "role": "",
      "template": "multixact %u contains update XID %u from before relfrozenxid %u"
    }
  ]
}

messages · message.4

{
  "limits": "",
  "message_id": "message.4",
  "path": "",
  "position": 4,
  "raw": {
    "id": "message.4",
    "primary_template": "multixact %u contains committed update XID %u from before removable cutoff %u",
    "severity_source": "ERROR",
    "sources": [
      "src.path.1"
    ],
    "sqlstate": "XX001"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.1"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "multixact contains committed update XID from before removable cutoff",
      "position": 0,
      "role": "",
      "template": "multixact %u contains committed update XID %u from before removable cutoff %u"
    }
  ]
}

messages · message.5

{
  "limits": "",
  "message_id": "message.5",
  "path": "",
  "position": 5,
  "raw": {
    "context": "bt_index_parent_check uses ShareLock and callback readonly=true, so this hint is not appended there.",
    "hint_condition": "bt_index_check (AccessShareLock; callback readonly=false)",
    "hint_template": "Retrying verification using the function bt_index_parent_check() might provide a more specific error.",
    "id": "message.5",
    "primary_template": "heap tuple (%u,%u) from table \"%s\" lacks matching index tuple within index \"%s\"",
    "severity_source": "ERROR",
    "sources": [
      "src.path.2",
      "src.path.3",
      "src.path.4"
    ],
    "sqlstate": "XX001"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.2",
    "src.path.3",
    "src.path.4"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "heap tuple ( , ) from table \" \" lacks matching index tuple within index \" \"",
      "position": 0,
      "role": "",
      "template": "heap tuple (%u,%u) from table \"%s\" lacks matching index tuple within index \"%s\""
    },
    {
      "kind": "hint",
      "literal": "Retrying verification using the function bt_index_parent_check() might provide a more specific error.",
      "position": 1,
      "role": "",
      "template": "Retrying verification using the function bt_index_parent_check() might provide a more specific error."
    }
  ]
}

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

sources · src.path.0

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/access/common/toast_compression.c",
  "position": 1,
  "sha256": "87d3c4337f09c991f5baefdbed6247fb93095c99f346ebb3622b8f5ee10e0064",
  "source_id": "src.path.0",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/access/common/toast_compression.c#L90"
}

sources · src.path.1

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/access/heap/heapam.c",
  "position": 2,
  "sha256": "57e3396476fc5d269bd2944b549a671f2699bf8ed43668e661090548ca206a16",
  "source_id": "src.path.1",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/access/heap/heapam.c#L6983"
}

sources · src.path.2

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "contrib/amcheck/verify_nbtree.c",
  "position": 3,
  "sha256": "a59ae7540a990e5a70e8eb9cedbcad7c62e3e86b1ad426142c8931ee188b752d",
  "source_id": "src.path.2",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/amcheck/verify_nbtree.c#L2760"
}

sources · src.path.3

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "contrib/amcheck/verify_nbtree.c",
  "position": 4,
  "sha256": "a59ae7540a990e5a70e8eb9cedbcad7c62e3e86b1ad426142c8931ee188b752d",
  "source_id": "src.path.3",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/amcheck/verify_nbtree.c#L252"
}

sources · src.path.4

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "contrib/amcheck/verify_common.c",
  "position": 5,
  "sha256": "8e591fc7b73760af0bea05987093064087b26f6b80856228d95f7c0d8e2d266a",
  "source_id": "src.path.4",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/amcheck/verify_common.c#L60"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:dbdd723801b62ed2589e8aebcfc69232e86c113c49266eae217b520b15eea342

Text language: en · english-manuals:dbdd723801b62ed2589e8aebcfc69232e86c113c49266eae217b520b15eea342