Restic repository health: what integrity checks prove—and what they do not

A team sees hundreds of snapshots and assumes the repository is healthy because new backups continue to complete. Months later, a storage fault has damaged older pack files that no recent run needed to read. The snapshot list looked normal; the problem appeared only when the team tried to recover historical data.

Restic provides repository checks precisely because successful writes and readable metadata do not cover every stored object forever. The checks can examine repository structure, references, indexes, snapshots, trees, blobs, and—when asked to read stored data—the integrity of pack contents.

The word “check” is easy to overgeneralize. Different modes provide different levels of evidence and costs. Operators need to know which one ran, what it covered, and when, rather than recording a single undifferentiated “repository healthy” status.

The standard check validates the repository’s structural consistency. It loads indexes, examines packs and references, and verifies that snapshots, trees, and blobs form a coherent repository view. It can identify missing objects, index problems, and other conditions that would make repository metadata inconsistent.

This is valuable and generally lighter than reading every stored byte from the backend. It should be part of routine maintenance, particularly after storage incidents or unusual interruptions. Keep the output and repository identity so a later investigation can see exactly what was checked.

A normal check is not a full media read. Restic documentation distinguishes metadata and structural checks from the options that download and verify pack data. If the storage system has silently corrupted an object whose metadata remains present, a structural pass alone may not exercise all of its content.

A full data check reads all repository pack files and verifies their stored content. This provides stronger evidence that the backend can return the data and that its cryptographic integrity checks succeed. It is the appropriate deeper test when repository damage is suspected.

The additional evidence has a real operational cost. Reading the whole repository can take substantial time, consume bandwidth, create object-storage request charges, and compete with normal backup activity. Large repositories therefore need a deliberate maintenance window and an understanding of backend pricing and rate behavior.

Keep “completed” separate from “clean.” A job that timed out halfway has not proved the unread half. Record bytes or scope covered, start and end time, restic version, and the final result. An incomplete full read should not silently inherit the status of the last successful one.

Restic can read a selected subset of repository data. This lets operators spread verification over time or sample the repository when a full read would be too expensive for every maintenance cycle. A deterministic sequence of non-overlapping subsets can eventually cover the whole repository; a random percentage is a sample, not guaranteed complete coverage.

Track what the schedule actually achieves. Repeating the same comfortable subset or running occasional random samples does not equal a documented full pass. If your policy says all stored data is read annually, maintain evidence that the selected parts collectively covered the repository during that period.

Subset strategy should follow repository size, change rate, storage cost, and recovery importance. A small critical repository may justify frequent full reads. A large archive may combine routine structural checks, rotating subsets, and less frequent full verification.

Restic can verify what is in the repository. It cannot know what should have been there. If a new uploads directory was never added, if a Docker deployment moved data to another volume, or if a database dump job selected the wrong database, the repository can be perfectly consistent and operationally incomplete.

Nor can an integrity check decide whether live application files were captured consistently. A byte-perfect copy of a database directory taken through an unsupported method may remain unusable. Application-aware backup and restore rules sit above repository integrity.

Pair repository checks with source coverage review. Compare current mounts, database inventory, and service configuration with the backup definition. Then inspect recovered content for recent, recognizable business data.

Integrity does not prove that storage credentials and the repository password will be available after the original server is gone. It does not measure how long it takes to provision a target, restore data, recreate permissions, start dependencies, or receive business approval.

It also cannot validate the chosen historical revision. Operators can restore the wrong snapshot correctly. They can recover files while omitting a required secret, role, extension, or external dependency. Those failures appear only when somebody rehearses the actual recovery.

Treat a repository check and a restore test as complementary controls. The first examines stored backup structure and data. The second examines people, credentials, infrastructure, procedure, application semantics, and timing.

Preserve the output and stop destructive maintenance while the situation is understood. Restic’s troubleshooting guidance recommends making a repository copy where possible and disabling regular operations—especially snapshot removal and pruning—before repair work. Continuing normal retention can remove information that would help recovery.

Investigate the storage cause as well as the repository symptom. Repeated ciphertext-verification failures can indicate hardware or backend problems. Repairing an index or damaged pack without addressing unreliable storage may only reset the clock until corruption returns.

Follow the current official instructions for the exact error and restic version. Repair operations can change repository state and some snapshot repair paths necessarily remove inaccessible data. They deserve a change record, a preserved pre-repair copy where feasible, and a new integrity check afterward.

For each repository, record the latest successful backup, latest structural check, latest data-read coverage, latest representative restore, and latest complete application recovery test. These dates answer different questions and should not collapse into one green indicator.

Set frequency according to size, backend characteristics, business impact, and retention. Run extra checks after storage migrations, unexplained backend errors, interrupted maintenance, or evidence of hardware trouble. Schedule repository work so it does not overlap carelessly with other maintenance.

The practical standard is not “we run check.” It is: the team knows which evidence is current, understands what remains unproven, and can restore a meaningful service within its agreed limits.