Learning Restic - Troubleshooting & Recovery

#Introduction

All episodes so far have built a system that runs smoothly. Episode 16 covers when nothing runs smoothly — because in real operations, that is guaranteed to happen. A backup fails at 3 AM, a restore does not find the file, or the repository is "locked".

The key: methodical diagnosis and drills done in advance, not panic in the moment.

#Debugging: RESTIC_DEBUG and --verbose

#Verbose: Seeing the Details

The verbosity level climbs from -v up to -vvvv:

restic backup /data -vv

-vv shows every processed file and the speed — useful for confirming the backup actually works or finding wrong path patterns.

#RESTIC_DEBUG: Internal Logs

For problems that need internal details (HTTP requests, chunking, keys):

RESTIC_DEBUG=1 restic backup /data

The debug log shows the internal trace including backend URLs and HTTP statuses. Don't run it permanently — only while investigating; the output can be very large.

#Common Cases and Their Solutions

#1. Repository Locked

Typical error

unable to create lock in backend: repository is already locked by ...

Another backup/prune process has not finished. Solution: wait for the process, or if it is clearly stuck (e.g. a dropped connection), remove the lock deliberately:

restic list locks
restic unlock

restic unlock removes locks that are no longer valid. Be careful: don't unlock while another process is genuinely still running — it can damage the repository.

#2. S3 Timeout / Access Denied

Typical S3 error

unable to open repository at s3:...
request failed: AccessDenied

Check in order: credentials (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY), bucket name, region, and endpoint version. Add timeouts via backend-specific options:

restic -o s3.list-objects-v1=true -o s3.connections=8 backup /data

#3. Wrong Password

Typical password error

wrong password or no key found

Usually a typo or an unexported env. Check with restic cat config, which requires the password:

restic cat config && echo "password OK"

If you truly forgot it, there is no way back — which is why episodes 3 and 13 stressed backing up the passphrase.

#Disaster Simulation: Restore Drills

Recovery is only reliable if it has been practiced. A full simulation:

rm -rf /home/user/Documents
restic snapshots
restic restore latest --target /tmp/restore \
  --path /home/user/Documents
mv /tmp/restore/home/user/Documents /home/user/Documents
diff -r /home/user/Documents /tmp/restore/home/user/Documents

The key: run it periodically in a test environment, record the duration (your RTO!), and also simulate the off-site backend (restore from S3/rest-server) — not just from the local repo.

#Recovery from a Corrupted Repository

When restic check reports missing blobs or hash mismatches (episode 11):

1. Identify the scope: run restic check and note the affected files/snapshots.
2. Recover from another source: if there is a second repo/off-site location, restore files from there.
3. Re-back up the data that still exists: missing chunks are regenerated from source files that are still available.
4. Manual repair only for specific cases: restic repair index to fix the index, or restic check --read-data-subset to find specific corrupt blobs.

restic repair index

#Conclusion

• -vv for backup details; RESTIC_DEBUG=1 for internal logs.
• Repo lock: restic list locks → restic unlock only when you are sure the process is dead.
• S3 error: check credentials, bucket, region, then tune the S3 options.
• Wrong password: test with restic cat config — and don't forget it.
• Routine disaster simulation: delete files → restore → verify → measure the duration.
• Corrupted repository: re-back up from source; manual repair only for specific cases.
• A dual-backend strategy is the last insurance against a corrupted repo.

In the next episode, episode 17, we refresh version knowledge: restic 0.19.x & the latest features — what 0.19.1 (Jul 2026) and 0.19.0 (Jun 2026) bring, the journey from 0.17 (2024) and 0.18 (2025) like zstd compression and lock-free index, and how to upgrade safely.