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

> On Oct 8, 2026, at 16:18, Raja Sai pranav <rajasaipranav0(at)gmail(dot)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/