Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

PostgreSQL 'invalid page in block' and checksum failures: preserve, locate, restore

Technical article
Backup & Recovery

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

PostgreSQL read a data page from disk and the page failed its checks, so it refused to use it. Causes include faulty storage or memory, or a bad copy. Do not start by switching a "fix" setting on. First copy the cluster, then work out which table or index owns the page, then restore that object from a good backup or rebuild it if it is an index. The setting zero_damaged_pages gets past the error by throwing away every row on the damaged page.

What the error means

In the REL_18_STABLE source, buffer_readv_report() in bufmgr.c produces these messages, all with the data-corrupted error code:

  • invalid page in block %u of relation "%s" (the error you normally see);
  • invalid page in block %u of relation "%s"; zeroing out page (when zero_damaged_pages is on);
  • forms for several pages at once, such as %u invalid pages among blocks %u..%u of relation "%s", with a detail line naming the first invalid block and a hint to see the server log for the others.

Before that, PageIsVerified() in bufpage.c checks a page just read from disk. If data checksums are enabled and the computed checksum differs from the stored one, it logs page verification failed, calculated checksum %u but expected %u. Even without a checksum failure, the page header must pass basic sanity checks (valid flags and consistent pointer positions). An all-zero page is accepted, because a zero page can legitimately appear after a crash while a relation was being extended.

Data checksums cover data pages only, not internal data structures or temporary files. They are set for the whole cluster, not per database or table. Checking the setting is simple: SHOW data_checksums;.

The default changed. The PostgreSQL 18 release notes say initdb now enables data checksums by default, with --no-data-checksums to disable, and that pg_upgrade requires matching checksum settings. That applies to clusters created with 18's initdb. A cluster created by an earlier release, or upgraded with checksums off, may not have checksums, so check each server.

Without checksums, a corrupt page may only be caught if the header looks wrong, or not at all.

Likely causes

Cause What you see How to confirm
Storage fault (disk, controller, SAN, cloud volume) Errors repeat on the same blocks; OS or hardware logs show I/O errors Operating system and array logs; read tests on the volume
Faulty memory Scattered checksum failures on different relations The amcheck documentation lists faulty RAM among causes it can detect; run hardware memory diagnostics
Bad copy or restore (file-level copy of a running cluster, incomplete transfer) Failure appears right after a restore or clone Compare to the source; re-check how the copy was made
Software defect in PostgreSQL, an extension or index operator class Index-only damage; amcheck reports invariants broken amcheck results; check recent upgrades and collation changes
Checksums disabled, so corruption went unseen for a while Error arrives long after the cause SHOW data_checksums; returns off

Prove the cause before changing anything

These steps are taken from the PostgreSQL documentation and have not been run. The relation in the error message is shown as a file path relative to the data directory, such as base/16384/16611.

  1. Preserve first. Copy the whole data directory, including WAL and tablespaces, to separate storage before you try repairs. A file-level copy needs the server shut down (or a consistent snapshot that includes the WAL). If you suspect failing hardware, image the disk rather than reading it repeatedly; see the related article on imaging a failing disk.
  2. Record the message. Note the block number and the relation in the error, and whether a page verification failed line precedes it.
  3. Find the object. Take the file number from the last part of the path in the message and run pg_filenode_relation(tablespace, filenode), which returns the relation for a file number; the tablespace can be given as zero for the database's default tablespace. In the other direction, SELECT pg_relation_filepath('schema.table'::regclass); returns the file path of a relation relative to the data directory. These are in the system administration functions. Whether the object is a table or an index decides the fix.
  4. Check how often it happens. pg_stat_database has checksum_failures and checksum_last_failure (NULL when checksums are disabled).
  5. Scan the cluster for failures. pg_checksums verifies every file, but the server must be shut down cleanly first, so it is not an online check. pg_checksums --check -D datadir is the default mode; -f filenode restricts it to one relation and -v lists files. The exit status is non-zero if any failure is found. Run it on your copy, not the live directory, if the original must stay online.
  6. Check logical consistency. The amcheck module provides bt_index_check for B-tree indexes and verify_heapam for tables. pg_amcheck runs them across a database, and has --install-missing to install amcheck if it is not yet there (this changes the database by adding an extension, so use it on a copy where possible). Its --parent-check and --rootdescend checks take strong locks that block writes, so do not run those on a busy production system. The documentation says amcheck "can only prove the presence of corruption; it cannot prove its absence", and that corruption it reports calls for finding the root cause.

Example (illustrative): on PG02 the application logs ERROR: invalid page in block 4182 of relation "base/16384/16611". pg_filenode_relation(0, 16611) returns public.invoices_idx_customer, an index. The table itself passes verify_heapam. The damage is confined to an index and the table is intact.

Fix

Decide by what the damaged page belongs to. Always work from the preserved copy.

The page belongs to an index

Rebuild it from the table, after confirming the table is sound. The REINDEX documentation says REINDEX rebuilds an index from the table's data and is a recovery method for corrupted indexes. A standard REINDEX locks out writes to the table; CONCURRENTLY avoids that. Caution: rebuilding an index does not remove the cause. The amcheck documentation says a REINDEX may not repair every corruption, and that you should find the root cause (for example failing storage) first. If the damaged index is on a system catalog, the REINDEX page describes a special procedure, and you should not improvise.

The page belongs to a table

Restore the table's data from a good source:

  • Restore from backup or point-in-time recovery to a recovery target before the damage; see the related article on recovery targets.
  • Restore the relation elsewhere and copy the affected rows back, if the rest of the table is sound.
  • Standby copy. If a physical standby has a good copy of the page, it may be a source. The documentation does not describe automatic page repair, so treat this as a manual, verified step. A damaged page on the primary may already have been replicated depending on how it was damaged; check before relying on it.

Last resort: salvage what you can

Destructive: zero_damaged_pages permanently loses rows. The developer-options documentation says it reports a warning, zeroes out the damaged page in memory and continues, that this "will destroy data, namely all the rows on the damaged page", and that you should not set it "until you have given up hope of recovering data from the damaged pages". It says to recreate the table or index before turning the parameter off, because zeroed pages are not forced to disk. Only superusers and users with the right SET privilege can change it.

ignore_checksum_failure is gentler but still risky: the documentation says it "may cause crashes, propagate or hide corruption, or other serious problems" and that if the page header itself is corrupt an error is raised regardless. The checksums page describes it as something to set temporarily when trying to recover from page corruption.

A practical salvage order: with the copy safe, extract readable rows from the damaged table into a new table with one of these settings on, record what was lost, and reconcile against a backup.

Do not

  • Do not enable checksums on a damaged cluster as a "fix". The pg_checksums documentation says that when enabling checksums, "each relation file block with a changed checksum is rewritten in-place", so a corrupt page would be given a valid-looking checksum.
  • Do not run zero_damaged_pages on the only copy.
  • Do not leave the cause unexplained. Corruption that recurs after a restore points back to hardware or memory.

Confirm the fix

  • The query that failed now succeeds, and a full sequential read of the table (for example pg_dump of the affected table, or pg_amcheck on the database) completes without error.
  • pg_checksums --check on a clean shutdown of the repaired data directory, or on a fresh restore, reports no failures.
  • Compare row counts and key totals with a trusted source (backup, standby or upstream system) so you know what you recovered.
  • The real proof for a restore is application-level: the data the business needs is present and correct.

What to watch afterwards

  • Enable checksums on new clusters (the default in 18) and check SHOW data_checksums; on older ones. Enabling or disabling later is an offline operation, and replicas must be changed consistently according to the pg_checksums notes.
  • Alert on pg_stat_database.checksum_failures increasing.
  • Schedule pg_amcheck against a restored copy of the database, so verification does not load production.
  • Monitor storage and memory error logs; recurring errors on different blocks suggest hardware.
  • Test restores on a schedule, because a backup taken after the corruption contains the damaged page.
  • Recurrence signal: new failures after replacing the object mean the cause was not the object.

Risks and limits

  • These commands and procedures are taken from the PostgreSQL 18 documentation and have not been run or lab-tested.
  • Message wording is from the 18 source. Releases before 18 may word messages differently and may not enable checksums by default.
  • pg_checksums requires a cleanly shut down cluster. It is not an online check.
  • The 18 source builds the relation in the message with relpathbackend, so it appears as a relative file path (as in the example), not a table name. Take the file number from the last part and use pg_filenode_relation.
  • amcheck can miss corruption; a clean result is not proof of a healthy database.
  • Repair choices depend on whether you have a good backup, a standby or neither; the documentation offers no automatic repair for a damaged table page.
  • Zeroed pages lose data permanently.

Sources

  • 28.2 Data Checksums — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
  • pg_checksums — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
  • F.1 amcheck — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
  • pg_amcheck — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
  • 19.17 Developer Options — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
  • Release 18 (E.7) — PostgreSQL Global Development Group, release date 2025-09-25, accessed 16 November 2026
  • REINDEX — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
  • 9.28 System Administration Functions — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
  • 27.2 The Cumulative Statistics System — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
  • 25.2 File System Level Backup — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
  • bufmgr.c, REL_18_STABLE — PostgreSQL source repository, source file, accessed 16 November 2026
  • bufpage.c, REL_18_STABLE — PostgreSQL source repository, source file, accessed 16 November 2026