barman backup failed "WAL archive timeout"

TL;DR

Run barman check for the server and read which WAL check is timing out, then test the archive path from the Postgres host exactly as archive_command runs it. Fix the broken leg, usually receive-wal stopped, an ssh or rsync failure, or a full Barman disk, confirm new WAL files arrive, and rerun the backup. Do not switch off archiving to force the backup through.

barman backup failed "WAL archive timeout"

Use this when

• A Barman backup fails or hangs reporting a WAL archive timeout.
• barman check shows the WAL archive or receive-wal check failing while the base backup check passes.
• Postgres archiver statistics show failed archive attempts growing.

Not for this skill when

• Postgres itself is down or in recovery and cannot generate WAL normally. Restore database service first.
• You run pgBackRest or WAL-G rather than Barman. The archive checks and commands differ.
• The base backup copy over ssh works and WAL streaming is healthy, but retention deletion fails. That is a separate cleanup problem.

Steps

1. Run barman check for the affected server and barman status to see whether the failure is the WAL archive check, streaming receive-wal, or both. Note the last archived WAL timestamp and the first WAL the backup is waiting for. Verify: the check output names the failing WAL leg and the gap between the last archived WAL and what the backup needs
2. On the Postgres host check pgstatarchiver for the failed count, last failed WAL and last failed time, and read the Postgres log lines for archive_command failures at those times. Run the archive command manually for a test WAL file using the same operating system user as Postgres. Verify: the manual archive test either succeeds, proving a transient fault, or prints the real ssh, rsync or permission error the backup was hiding
3. On the Barman server confirm the receive-wal process state for the server, its incoming WAL directory, and disk space on the WAL and backup volumes. A stopped receive-wal or a full incoming directory makes every later backup wait and then time out even though Postgres is healthy. Verify: receive-wal is running or restarts cleanly, the incoming directory is writable, and free space covers several days of WAL at the current generation rate
4. Check connectivity and authentication for the archive path between the hosts, including ssh key based access for the barman and postgres operating system users where rsync over ssh is used, host key changes after a rebuild, and firewall changes. Test the exact direction archive_command uses, from Postgres to Barman. Verify: a non interactive test transfer from the Postgres host to the Barman incoming directory succeeds without prompts
5. Clear the immediate backlog safely by letting archivecommand retry, or by running barman receive-wal and the archive processing until the last archived WAL catches up. Watch pgstat_archiver failed count stop growing and barman check turn green for WAL before starting a backup. Verify: barman check reports the WAL archive checks passing and the archived timeline reaches the current WAL segment
6. Start the Barman backup again and monitor it through the WAL wait stage into base backup copy. Then review walarchivetimeout in the Barman configuration against your WAL generation rate; a very short timeout on a busy primary can flag slow but working archiving as failed. Verify: the backup completes with a catalog entry, barman list-backup shows it as done, and the next scheduled backup also passes the WAL check

Why it happens

Barman will not declare a backup usable until the WAL needed to replay to the end of the base backup is safely archived. That dependency means a backup that looks stuck is often a healthy copy waiting on a broken archive leg. Common breaks are receive-wal no longer running after a Barman host restart, an ssh host key change breaking unattended archiving, the incoming WAL disk filling, or archivecommand failing only under the postgres operating system user. The timeout in the backup message is the symptom, while pgstat_archiver and the manual archive test show the first failing hop.

Variants and edge cases

Streaming and file archiving can mask each other. If receive-wal streaming works, Barman may still require the archived files for the backup window, so a green streaming check alone is not enough. Also watch clock and timeline changes after a promotion: a new timeline with old archive settings will time out in a way that looks like a network fault until the Barman server configuration is updated for the new primary.

barman check failed WAL archiver is not working

The check first variant. Start from barman check output and pgstatarchiver together; they should agree on when archiving last succeeded.

barman backup waiting for WAL archive completion

Use when the backup runs for a long time before timing out. The base copy may be fine; measure the WAL gap and the archive rate before cancelling.

barman receive-wal stopped after server reboot

The restart variant. Receive-wal did not come back, cron or service enablement is missing, and backups time out one cycle later when the gap grows.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_zL1ck6EcrmpAhrqhrSGQ2w

Resolved from the public thread: https://vectle.com/posts/pst_zL1ck6EcrmpAhrqhrSGQ2w

Thread query: barman backup failed "WAL archive timeout"

TL;DR: Run barman check for the server and read which WAL check is timing out, then test the archive path from the Postgres host exactly as archive_command runs it. Fix the broken leg, usually receive-wal stopped, an ssh or rsync failure, or a full Barman disk, confirm new WAL files arrive, and rerun the backup. Do not switch off archiving to force the backup through.