Add a hint to the "WAL summaries are required" errors

From: Raja Sai pranav <rajasaipranav0(at)gmail(dot)com>
To: pgsql-hackers(at)lists(dot)postgresql(dot)org
Subject: Add a hint to the "WAL summaries are required" errors
Date: 2026-10-08 08:18:14
Message-ID: CAPHduZC1gKfjn+nWkRE=t_JckKW9VGA259v0uuz=8tW+CwFn8g@mail.gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hi hackers,

When an incremental backup can't be taken because the WAL summaries for the

required range are missing or incomplete, the server reports:

ERROR: WAL summaries are required on timeline 1 from 0/02000028 to

0/05000028, but the summaries for that timeline and LSN range are
incomplete

DETAIL: The first unsummarized LSN in this range is 0/02000028.

That says what is wrong but not what to do. By the time these two errors are

raised in PrepareForIncrementalBackup(), the server has already waited for

WAL summarization to catch up (a summarizer that is stuck gets its own
error),

so the summaries are not going to appear: summarization was off for part of

the range -- commonly because summarize_wal was enabled only after the full

backup was taken -- or the summaries were removed after
wal_summary_keep_time.

In those cases the only way forward is a new full backup. I hit this while

testing incremental backups on PG 18, and several blog posts explain exactly

this error and fix to users.

The attached patch adds the same hint to both errors:

HINT: Take a new full backup if WAL summarization was not enabled for
this

whole range or the required summaries have been removed.

One question on wording: the error can also come from WAL generated with

wal_level=minimal (src/bin/pg_combinebackup/t/007_wal_level_minimal.pl). The

remedy is the same, but the hint does not name that case. Would a shorter

"Take a new full backup." be preferable?

I checked it on master by turning summarize_wal off for part of the range,

which now reports the hint after the DETAIL line. The existing TAP test

(007_wal_level_minimal.pl) matches only the main message, so it is

unaffected.

Regards,

Sai Pranav

Attachment Content-Type Size
v1-0001-Add-a-hint-to-the-WAL-summaries-are-required-erro.patch application/octet-stream 2.1 KB

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Chao Li 2026-10-08 08:33:22 Re: pg_resetwal: add --cluster-state option
Previous Message ZizhuanLiu X-MAN 2026-10-08 08:12:26 Re: Optimize MCV stats for sortable types and utilize sorted-order properties