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

NetLeverage
NetLeverage

pgBackRest backup fails: 'WAL segment was not archived before the timeout'

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.

This error means pgBackRest asked PostgreSQL to complete a WAL segment and then waited for that segment to appear in the repository, and it did not appear in time. Common reasons include that PostgreSQL's archive_command is not running pgBackRest at all, it names a different stanza from the one you are checking, or it is failing, or the push is slower than archive-timeout. The fastest way to find which is to compare what pgbackrest check reports with what PostgreSQL's archiver and server log say.

What the error means

In pgBackRest's source, the function walSegmentFind() in src/command/archive/find.c throws an ArchiveTimeoutError when no archived copy of a WAL segment is found and a timeout is set. The message has the form WAL segment %s was not archived before the %ms timeout, followed by three hints: check the archive_command for correct options (especially --stanza), check the PostgreSQL server log for errors, and run the start command if the stanza was previously stopped.

A real example from a user report on the PostgreSQL mailing list shows typical output, including the code [082]:

ERROR: [082]: WAL segment 000000010000001D0000001E was not archived before the 60000ms timeout
HINT: check the archive_command to ensure that all options are correct (especially --stanza).
HINT: check the PostgreSQL server log for errors.
HINT: run the 'start' command if the stanza was previously stopped.
INFO: check command end: aborted with exception [082]

The command reference says check validates that pgBackRest and archiving are configured correctly for a stanza, and the user guide adds that it forces a WAL segment to archive by calling pg_create_restore_point('pgBackRest Archive Check') and a WAL switch. The backup command also waits for the WAL segments it needs. The wait is governed by archive-timeout: the reference lists a default of 1 minute and an allowed range of 100 ms to 1 day, and says it applies to check and backup. The user guide likewise says the default is 60 seconds and that you should increase the option if archiving a segment takes longer.

The error is therefore a symptom, not a diagnosis. The segment is missing from the repository for some reason. A maintainer replying in a GitHub issue with the same error explains that check only looks at the repository to see whether PostgreSQL has pushed the archive using archive_command, so there should be a failure or a success visible in the PostgreSQL logs.

Likely causes

Cause What you see How to confirm
archive_command does not call pgBackRest, or archive_mode is off pg_stat_archiver shows no archived count increase; no archive-push entries SHOW archive_mode; and SHOW archive_command;
Stanza name in archive_command differs from the one passed to check The server log shows successful pushes to one stanza; check fails on another Compare the --stanza values in archive_command and in your command (a reply in the mailing-list thread gave this as the diagnosis: "in your check command you use a different stanza name from the configuration")
archive_command is failing failed_count rising and last_failed_wal set in pg_stat_archiver Query pg_stat_archiver; read the server log for the command's output
Command exits with a status above 125 or is not found pg_stat_archiver shows nothing Read the server log; the PostgreSQL documentation says these failures are not reported in pg_stat_archiver
Stanza stopped Hint about the start command Run pgbackrest info for the stanza and check for a stop state
Push slower than archive-timeout Archiving works but late; last_archived_time trails Compare last_archived_wal to the segment named in the error
Repository unreachable or full Push errors in the server log Read the log; check repository space
More than one primary archiving to the same stanza A different error: duplicates found in archive for the segment, with a hint about multiple primaries Source shows a separate ArchiveDuplicateError; not a timeout

Prove the cause before changing anything

These commands come from the pgBackRest and PostgreSQL documentation and have not been run. They are read-only, except that check asks PostgreSQL to create a restore point and switch WAL.

  1. See what PostgreSQL is configured to run. SHOW archive_mode; and SHOW archive_command;. The documented form is archive_command = 'pgbackrest --stanza=demo archive-push %p' with archive_mode = on. PostgreSQL's reference says archive_command is only used if archive_mode was enabled at server start, and that an empty string disables archiving while WAL accumulates. archive_mode can only be set at server start.
  2. Read the archiver's own counters. SELECT archived_count, last_archived_wal, last_archived_time, failed_count, last_failed_wal, last_failed_time FROM pg_stat_archiver; (columns per the statistics views). Rising failed_count means the command ran and failed. No change with nothing failed means the command may never be running.
  3. Read the PostgreSQL server log for the archive command's output. The archive command's own error output appears here.
  4. Run the check with more output. The guide's form is sudo -u postgres pgbackrest --stanza=demo --log-level-console=info check. The maintainer in the issue also suggested adding a [global:archive-push] section with log-level-console=detail to expose more detail in the PostgreSQL log.
  5. Check the stanza state. pgbackrest --stanza=demo info reports stanza status and the WAL archive minimum and maximum. If the stanza was stopped, pgbackrest --stanza=demo start is the documented counterpart to stop.
  6. Check the size of the gap. If last_archived_wal is old and pg_wal is growing, archiving has been failing for a while. The PostgreSQL documentation warns that pg_wal keeps filling until the situation is resolved, and that a full file system causes a PANIC shutdown.

Example (illustrative): on DB01, pgbackrest --stanza=main check fails with the 60000ms timeout. SHOW archive_command; returns pgbackrest --stanza=prod archive-push %p. The cluster is archiving to stanza prod, so check against main never sees those segments. The fault is the stanza name, not the repository.

Fix

Fix the cause you proved. Do not just raise the timeout.

  • Wrong or missing archive_command. Set it to call archive-push with the right stanza and %p, set archive_mode = on, and note the guide's statement that the cluster must be restarted after these changes and before a backup. A restart interrupts service; schedule it.
  • Stanza mismatch. Use the same stanza name in the command you run and in archive_command. Do not rename in one place only.
  • Failing command. Fix what the server log shows (permissions, repository path, repository host, authentication, disk space). archive_command must return a zero exit status only on success, because PostgreSQL then recycles the segment.
  • Stopped stanza. Run start for the stanza.
  • Genuinely slow archiving. Raise archive-timeout using the unit forms the reference shows (such as 1m, 100ms, 1d), and consider asynchronous archiving. The reference says archive-async enables asynchronous archive-push and archive-get; the guide shows archive-async=y with a spool-path and process-max set in the [global:archive-push] section. The guide says a spool path is required. The reference advises a local POSIX filesystem for it, not inside pg_wal, and not NFS or CIFS.
  • Queue limits. The reference describes archive-push-queue-max: when the limit is reached, pgBackRest reports WAL as archived and drops it with a warning, and point-in-time recovery is not possible past that point. Do not set a low limit to hide a timeout.

More than one cause can produce this error, so one change may not clear every case.

Confirm the fix

  • pgbackrest --stanza=demo --log-level-console=info check ends with check command end: completed successfully.
  • pg_stat_archiver shows archived_count increasing and last_archived_time current, with no new last_failed_time.
  • A full or differential backup completes, and pgbackrest info lists the WAL range covering it.
  • The real proof is a test restore of the backup, with archive recovery, onto a separate server. A passing check shows the archive path works; it does not show that you can restore. Use the restore procedure in the "Restore" section of the pgBackRest user guide.

What to watch afterwards

  • Alert on failed_count growth and on last_archived_time older than your archive interval.
  • Alert on pg_wal volume use.
  • Run check on a schedule, and after any change to archive_command, stanza or repository.
  • With archive-async, watch the spool directory and queue limits.
  • Recurrence signal: a timeout on check while pg_stat_archiver shows no failures can point to naming or configuration rather than performance.

Risks and limits

  • These commands have not been run or lab-tested.
  • The error text and hints are from the pgBackRest main-branch source and user reports; the user guide does not list them. The [082] code appears in user reports, not in the pgBackRest documentation pages.
  • Confirm option defaults and ranges against the live configuration reference before changing production.
  • The configuration reference gives archive-timeout in seconds ("Set maximum time, in seconds, to wait for each WAL segment", example archive-timeout=30); a report with archive-timeout=3000 shows a 3000000ms timeout in the message. Use explicit units such as 1m.
  • Guidance on stanza mismatch comes from a mailing-list reply, not from the vendor documentation.
  • Restarting PostgreSQL to change archive_mode interrupts service.

Sources