Check repository integrity

A repository can sit on a slowly failing disk for years. It accepts new snapshots while old data rots underneath. Repository checks validate the structure and can read the stored data to detect damage, before the day you need that data back.

Checks complement restore drills. They don’t replace them. A check proves the repository’s bookkeeping and bytes are intact. Only a restore drill proves you can turn those bytes into a working system.

Two levels of checking

Run both on the practice repository:

restic check
restic check --read-data-subset=10%

Plain restic check verifies the structure. It confirms every snapshot’s metadata is consistent and every data chunk that should exist is referenced correctly. It’s fast because it reads almost none of the actual data.

create exclusive lock for repository
load indexes
check all packs
check snapshots, trees and blobs
no errors were found

no errors were found is the line you want.

The --read-data-subset=10% variant also downloads 10% of the stored data and verifies it against its checksums. This is what catches bit rot and truncated uploads. The structural check can’t see those.

Schedule rotating coverage

Reading all data on every check would hammer a large repository and burn bandwidth on remote storage. Record how long a check takes and what it finds. Then design a schedule that eventually covers everything without overwhelming the backup target.

The subset syntax supports rotation directly:

restic check --read-data-subset=1/10   # week 1: first tenth
restic check --read-data-subset=2/10   # week 2: second tenth

Cycle from 1/10 to 10/10 and every byte gets verified once every ten weeks, at a tenth of the weekly cost.

When a check fails

Investigate before you prune or rewrite anything. A failed check means the repository holds damage. Your instinct will be to “clean it up”. Resist it.

Pruning rewrites and deletes data. It can turn a partially damaged repository into a thoroughly broken one, and it destroys the evidence of what went wrong.

Preserve the evidence first: the error output, the affected files, and a second copy of whatever still restores. Then diagnose. Damaged repositories can often be partially recovered, but only if you didn’t rewrite them in a panic.