restic check
restic check is the primary tool for ensuring your backup data is safe and reachable. It scans the repository's metadata (indexes and snapshot files) and can optionally verify the actual contents of your backup blobs to detect bit rot or storage failures.
Think of check as a "File System Check" (fsck) for your backups. It doesn't back up new data; it proves that what you've already backed up is still perfect.
Basic Syntax
restic check [flags]
Verification Levels
# Level 1: Quick metadata check (Fastest)
# Verifies that all files listed in snapshots exist in the repository index.
restic check
# Level 2: Random sample verification
# Reads 10% of the actual data blobs to ensure they can be decrypted and hashed correctly.
restic check --read-data-subset=10%
# Level 3: Full data verification (Slowest)
# Reads every single byte of data in the repository. Recommended monthly.
restic check --read-data
Key Flags
| Flag | Description |
|---|---|
--read-data | Read all data packs and verify their integrity (Heavy I/O) |
--read-data-subset=N% | Read a specific percentage of data packs (e.g., 5%, 10%) |
--read-data-subset=n/m | Check subset n of m (e.g., 1/5 to check 20% in rotation) |
--with-cache | Use the local cache for verification (faster, but less thorough for remote repos) |
Practical Examples
1. Daily Cron Check (Fast)
Use a small subset to catch storage issues early without high bandwidth costs.
restic check --read-data-subset=2%
2. Rotational Verification (Systematic)
Break a full check into 5 parts and run one part each day. By Friday, you've checked 100% of the data.
# Day 1
restic check --read-data-subset=1/5
# Day 2
restic check --read-data-subset=2/5
# ... and so on
3. Verification After a Prune
Always run a basic check after running restic prune to ensure no active data was accidentally deleted.
restic forget --keep-last 7 --prune
restic check
Understanding the Checks
| Level | What is Checked | Detection Capability |
|---|---|---|
| Metadata | Indexes, Snapshots, Trees | Missing index files, broken pointers. |
| Packs | Pack file structure & headers | Truncated files, interrupted uploads. |
| Data | Actual file content hashes | Bit rot, storage medium degradation (Silent corruption). |
Common Pitfalls
| Pitfall | Consequence | Prevention |
|---|---|---|
Never running --read-data | Undetected bit rot. You only find out a file is corrupt during a crisis restore. | Schedule a full --read-data or rotational subset check monthly. |
| Checking over slow WAN | High latency and bandwidth costs for S3/Remote repos. | Use subset checks or run the check from a machine closer to the storage. |
| Ignoring Errors | If check fails, the repo is in an inconsistent state. | Investigate immediately using restic rebuild-index or restic recover. |
Examples with Output
1. Standard Metadata Check (Quick)
Command:
restic check
Output:
using temporary cache in /tmp/restic-check-cache-582
repository a7b2c9d opened successfully, password is correct
created new cache in /tmp/restic-check-cache-582
create exclusive lock for repository
load indexes
check all packs
check snapshots, trees and blobs
no errors were found
2. Random Data Subset Verification (5%)
Command:
restic check --read-data-subset=5%
Output:
repository a7b2c9d opened successfully, password is correct
load indexes
check all packs
check snapshots, trees and blobs
read 5.0% of data packs
no errors were found
3. Full Data Verification (Thorough)
Command:
restic check --read-data
Output:
repository a7b2c9d opened successfully, password is correct
load indexes
check all packs
check snapshots, trees and blobs
read 100% of data packs
no errors were found
4. Check Specific Snapshots Only
Command:
restic check --with-cache --host app-01
Output:
repository a7b2c9d opened successfully, password is correct
load indexes
check all packs
check snapshots, trees and blobs
[app-01] check snapshots
no errors were found
5. Failed Check (Missing Pack)
Command:
restic check
Output:
repository a7b2c9d opened successfully, password is correct
load indexes
check all packs
pack 58f2d1c9: not found in index
check snapshots, trees and blobs
Fatal: repository contains errors
What's Next?
If you found errors, head to the Troubleshooting & Repair section.