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

On Oct 8, 2026, at 16:18, Raja Sai pranav <rajasaipranav0@gmail.com> wrote:

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

<v1-0001-Add-a-hint-to-the-WAL-summaries-are-required-erro.patch>

I agree that a shorter, more general hint would be preferable. I'm not sure it's helpful to make the advice conditional on users determining whether WAL summarization was disabled or summary files were removed. As you mentioned, wal_level=minimal can also cause the error. How about:
```
Consider taking a new full backup to use as the basis for future incremental backups.
```

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/

Hi Sai,

I tried the patch on master (v1 applies cleanly, and 007 still passes
3/3) and reproduced the error on several paths, including the
wal_level=minimal case via 007. The hint shows up in all of them.

Would a shorter "Take a new full backup." be preferable?

I think there is a case for it. On the minimal path the hint still
fires, but its two causes do not really fit: summarize_wal is off there
only because minimal requires it -- the actual reason is that the
summarizer reaches that WAL and skips it on purpose (fast_forward) --
and nothing was removed. And even in the main case the first cause is
more a symptom than the condition: with the WAL still on disk, enabling
summarize_wal after the full backup does not error, since the summarizer
backfills from the oldest WAL present; it only fails once that WAL has
been recycled before summarization caught up.

So the remedy-only form you suggested reads correctly in all of them.
If you would rather keep naming the minimal case, there is existing
wording to mirror at xlog.c:6037:

Use a backup taken after setting "wal_level" to higher than "minimal".

Happy to share the repro script if it helps.

Regards,
Manu

Hi Chao, Manu,

Thanks both , that's a good correction. I didn't realize the summarizer
backfills from the oldest WAL still on disk, so "summarization was not
enabled" isn't really the trigger; it's WAL being recycled before
summarization catches up. Dropping the conditional causes entirely also
sidesteps the wal_level=minimal case not fitting them, as Manu pointed out.

v2 attached, using Chao's wording:

HINT: Consider taking a new full backup to use as the basis for future
incremental backups.

Re-verified the summaries-removed path on master with the new wording.
Manu, thanks also for independently confirming it on wal_level=minimal and
that 007 still passes saves me chasing that path myself.

Regards,
Sai Pranav

On Thu, Oct 8, 2026 at 3:04 PM Manu <manuelreyesbravo@gmail.com> wrote: