restic check vs --read-data vs --read-data-subset: what each one proves

restic check: the structure

restic check

Plain restic check loads the index and every snapshot, walks the directory trees and makes sure that everything they point to is listed in the index and that the pack files exist. It does not download the file contents.

• Catches: missing pack files, a broken index, snapshots that point to data which isn't there — the typical damage after an interrupted prune or files deleted on the storage side.
• Misses: pack files that exist but whose contents are damaged (bit rot, a bad disk, a half-written upload).
• Cost: reads metadata only. Usually seconds to minutes, cheap even on S3.

By default check uses a fresh temporary cache, so it doesn't trust what is already on the local disk. --with-cache reuses the normal cache — faster on remote repositories, at the price of trusting it.

restic check --read-data: every byte

restic check --read-data

This additionally downloads every pack file and verifies the hash of every piece of data inside it. It is the only check that proves the whole repository can be read back.

• Catches: everything plain check catches, plus damaged data in any snapshot, old or new.
• Cost: reads the entire repository. On a local disk that is hours for a few terabytes. On cloud storage it means downloading all of it — time, bandwidth and egress fees that can add up to real money for large repositories.

restic check --read-data-subset: a slice at a time

You rarely need to read everything in one go. --read-data-subset reads only part of the pack files, in one of three forms:

restic check --read-data-subset=1/7   # part 1 of 7 fixed parts
restic check --read-data-subset=5%    # a random 5% of the pack files
restic check --read-data-subset=10G   # random pack files, about 10 GiB in total

The n/t form is the useful one for full coverage: the repository is split into t fixed groups, so running parts 1 to 7 on seven nights reads every pack file once a week. The random forms are good for spot checks and for capping cost, but they don't promise that every pack is ever read.

One line in a nightly job covers the whole repository every week — date +%u is the day of the week, 1 to 7:

restic check --read-data-subset="$(date +%u)/7"

For a big cloud repository, stretch the cycle — "$(date +%d)/31" reads about 1/31 of it per night and the whole repository each month (on shorter months the last parts are read the next month).

How often to run what

• Plain check — after every backup or at least daily. It's cheap and catches most "something deleted files" problems.
• Read-data in slices — nightly, so the whole repository is re-read once a week (local disk) or once a month (cloud).
• A restore test — after every backup. A check proves the repository is consistent; only a restore proves the data you care about is in it. See How to test that your restic backups actually restore.

Run checks when no prune or forget --prune is running on the same repository.

When check reports errors

restic check exits non-zero when it finds a problem, so a script can alert on it. If it does:

1. Stop pruning that repository until you understand the problem — prune deletes data, and you may need what is still there.
2. Read the exact error. "pack not found" is a missing file on the storage side; hash mismatches mean damaged contents.
3. If you can, copy the repository before you change anything.
4. Follow the troubleshooting guide in the restic documentation. Recent versions have restic repair index and restic repair snapshots for exactly these cases.
5. Run a new backup — after a repair, the next backup re-uploads data that went missing, as long as it still exists on the source.