Pg-archivecleanup Must Specify Oldest Kept Wal File May 2026

pg_archivecleanup [options] archive_directory oldestkeptwalfile When the utility runs, it needs the oldestkeptwalfile argument to determine which files are safe to delete. If you run the command without this argument, or if the argument is missing due to a scripting error, PostgreSQL refuses to guess. It stops execution and throws this error.

Why does it refuse to guess? Because deleting the wrong WAL files can render your backups useless. If pg_archivecleanup were to assume a default behavior (like "delete everything older than the newest file"), you might lose the ability to recover your database to a specific point in time. Therefore, the error is a protective measure, forcing the administrator (or the script) to explicitly state, "I want to keep this specific file and newer ones, delete the rest." This error typically does not happen when an administrator manually types a command into the terminal (as they would immediately see the missing argument). It most frequently occurs in automated environments and misconfigured scripts. 1. Misconfigured archive_cleanup_command The most common scenario is within the postgresql.conf configuration file. PostgreSQL allows you to automate WAL cleanup using the archive_cleanup_command parameter. This command is executed every time the server restarts or switches to a new WAL file. pg-archivecleanup must specify oldest kept wal file

# INCORRECT CONFIGURATION archive_cleanup_command = 'pg_archivecleanup /var/lib/postgresql/archive' Here, the administrator has provided the path to the archive directory but forgot to include the placeholder for the file name. In PostgreSQL, %r is the placeholder that represents the name of the last file that needs to be kept. Why does it refuse to guess

A common misconfiguration looks like this: Therefore, the error is a protective measure, forcing

However, pg_archivecleanup does not work on "auto-pilot." It requires a reference point—a specific file that acts as the anchor. It will look at the archive directory, identify the sequence of files, and delete everything older than the specified file, leaving the specified file and everything newer untouched. The error message "pg_archivecleanup must specify oldest kept wal file" is exactly what it sounds like, but with a technical nuance.

# If $OLDEST_FILE is empty/null... pg_archivecleanup /mnt/wal_archive The system sees the directory but no file argument, resulting in the error. This often happens when a script is looking for a .backup file to anchor the cleanup, and no such file exists yet. While less common, severe permission issues can sometimes prevent `pg_archivecleanup

This error is a safeguard, a built-in mechanism designed to prevent catastrophic data loss. However, to the uninitiated, it can appear as a roadblock in an automated script or a maintenance task.