Check and Safely Repair a Redis AOF

You will check a Redis append-only file without changing it, identify the last valid byte when it is damaged, and understand the point at which repair would discard data. Allow about 10 minutes for a single file, plus time to make and verify a backup before any repair. The examples use the redis-tools package installed on this machine, version 5:7.0.15-1ubuntu0.24.04.4.

1. Check the installed tool and the file

The local manual page describes redis-check-aof filename and says that the utility checks a dumped AOF file. It does not document an option list. The installed binary accepts a filename and also recognises --fix, so confirm the binary and package before relying on behaviour from another Redis release.

$ command -v redis-check-aof
/usr/bin/redis-check-aof
$ dpkg-query -W -f='${Package} ${Version}\n' redis-tools
redis-tools 5:7.0.15-1ubuntu0.24.04.4
$ test -f /var/lib/redis/appendonly.aof && echo "AOF exists"
AOF exists

Replace /var/lib/redis/appendonly.aof with the actual path from your Redis configuration or service files. Do not guess a path and do not run the checker against a file that belongs to a different Redis instance. Reading a file normally needs no elevated privileges. If the file is readable only by the redis account, use an approved maintenance shell or narrowly scoped privilege rather than changing its ownership.

2. Run a read-only integrity check

Start without --fix. This check does not alter the AOF. Quote the path so whitespace or shell metacharacters in a supplied path cannot become additional shell syntax.

$ AOF='/var/lib/redis/appendonly.aof'
$ redis-check-aof "$AOF"
Start checking Old-Style AOF
AOF analyzed: filename=/var/lib/redis/appendonly.aof, size=123456, ok_up_to=123456, ok_up_to_line=42, diff=0
AOF /var/lib/redis/appendonly.aof is valid

The size and line number vary. The useful result is the final validity message and an exit status of zero:

$ printf 'exit status: %s\n' "$?"
exit status: 0

A valid result means this utility accepted the file's AOF protocol structure. It is not a backup, and it does not prove that the file belongs to the intended Redis instance or that every application-level value is correct.

3. Read a failure before touching the file

A damaged or incomplete tail normally produces a non-zero status and reports the last accepted offset. For example, the installed program reports this shape of result:

$ redis-check-aof "$AOF"
Start checking Old-Style AOF
AOF /var/lib/redis/appendonly.aof format error
AOF analyzed: filename=/var/lib/redis/appendonly.aof, size=123462, ok_up_to=123456, ok_up_to_line=42, diff=6
AOF /var/lib/redis/appendonly.aof is not valid. Use the --fix option to try fixing it.
$ printf 'exit status: %s\n' "$?"
exit status: 1

Record ok_up_to and diff. The offset is diagnostic evidence, not permission to truncate automatically. First check whether Redis is still writing the file, stop or isolate the affected service according to your operational runbook, and preserve the original. Do not repair an active AOF while its server may append more data.

An absent file is a different failure. A message such as Cannot open file ...: No such file or directory points to a path, mount or service configuration problem. It is not proof that the AOF is corrupt.

4. Make a recoverable copy before repair

Use a destination on storage with enough free space, and preserve metadata where possible. The copy is a safety net, not a substitute for a tested backup.

$ cp --preserve=all -- "$AOF" "$AOF.before-redis-check-aof"
$ stat --format='backup: %n (%s bytes)' "$AOF.before-redis-check-aof"
backup: /var/lib/redis/appendonly.aof.before-redis-check-aof (123462 bytes)

Keep the backup until Redis has restarted successfully and the recovered dataset has been checked. If you discover that the wrong file was selected, stop here and remove neither file. Restore the original only through your service's documented recovery procedure.

5. Confirm the proposed truncation interactively

Run the installed option only after the service is safely stopped or the file is otherwise no longer changing:

$ redis-check-aof --fix "$AOF"
Start checking Old-Style AOF
AOF /var/lib/redis/appendonly.aof format error
AOF analyzed: filename=/var/lib/redis/appendonly.aof, size=123462, ok_up_to=123456, ok_up_to_line=42, diff=6
This will shrink the AOF /var/lib/redis/appendonly.aof from 123462 bytes, with 6 bytes, to 123456 bytes
Continue? [y/N]:

At this prompt, press Enter or type N unless you have reviewed the offset, backup and expected data loss. The default is to abort. A repair is not an undoable edit: it truncates the file at the accepted boundary. If the prompt describes a surprising amount of data, abort and investigate the disk, process shutdown and Redis logs first.

If you confirm with y, check the result immediately:

$ redis-check-aof "$AOF"
Start checking Old-Style AOF
AOF analyzed: filename=/var/lib/redis/appendonly.aof, size=123456, ok_up_to=123456, ok_up_to_line=42, diff=0
AOF /var/lib/redis/appendonly.aof is valid
$ printf 'exit status: %s\n' "$?"
exit status: 0

If the repair fails or the post-repair check is not valid, do not repeatedly truncate the backup or original. Keep the files unchanged and use the Redis logs and the saved copy for a deliberate recovery decision. The official Redis persistence guidance also recommends running the check without --fix first and understanding the reported offset.

6. Start Redis and verify the recovery

Only after the repaired file passes should you follow your normal service start procedure. Starting a database service may affect clients, so use the maintenance window and service account expected by your deployment.

$ sudo systemctl start redis-server
$ sudo systemctl is-active redis-server
active
$ redis-cli ping
PONG

The sudo commands are examples of operations that normally require elevated privileges; the checker and redis-cli do not inherently require them. Confirm the service logs show a clean AOF load, then verify representative keys or application health. Do not delete the backup until those checks and your retention policy say it is safe. If the service will not start, stop it and restore the pre-repair copy using the documented Redis service recovery process, then investigate rather than overwriting evidence.