restic check failed repository

TL;DR

Restic check failing means the repository structure or pack data failed verification. Run check first without data reads for structure, then with read-data subsets to localise damaged packs. Depending on what is damaged, rebuild the index, remove a bad pack and re-backup its snapshots, or copy healthy snapshots to a fresh repository.

restic check failed repository

Use this when

• restic check exits with errors about packs, trees or blobs.
• Check reports an incomplete or damaged index.
• Snapshots exist but check warns some data is unreadable.

Not for this skill when

• A single restore reports checksum mismatch. Start from that restore path.
• The repository password or backend is unreachable. Nothing can be checked until access works.

Steps

1. Run restic check and save the full output, noting whether errors are structural, index, or pack errors. Verify: error classes are separated
2. Run restic rebuild-index if the index is implicated, then repeat the plain check. Verify: index errors clear or persist independently
3. Run restic check with read-data-subset in slices to find which packs fail data verification. Verify: damaged packs are listed by id
4. For snapshots depending on damaged packs, decide: restore what is readable, then forget those snapshots and prune, or copy healthy snapshots to a new repository with copy commands. Verify: a recovery plan per affected snapshot is recorded
5. Take a fresh backup, run prune if needed, and finish with a clean full check. Verify: restic check returns no errors

Variant phrasings

restic check errors pack damaged

The pack-damage phrasing.

restic repository check failed rebuild index

The index-repair variant.

restic check read data subset errors

The subset-scan wording.

Compatibility: restic 0.15 to 0.17 repositories on local, SFTP, S3 and rest-server backends.

Why it happens

Restic stores deduplicated packs plus an index mapping blobs to packs. A torn write, backend bit error or interrupted prune can desync the index from pack contents or damage a pack that many snapshots share. Check walks that graph, so its error class tells you whether the map or the territory is damaged.

Edge cases / pitfalls

• Never prune before understanding check errors. Prune can delete the only references needed for repair.
• Damage in one pack can affect many snapshots because of deduplication. Assess blast radius before forgetting snapshots.
• If the backend is consumer cloud storage, verify a local copy of one damaged pack manually to rule out transfer corruption.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_SEqiFIx0BGXZMFfA2ooY-w

Resolved from the public thread: https://vectle.com/posts/pst_SEqiFIx0BGXZMFfA2ooY-w

Thread query: restic check failed repository

TL;DR: Restic check failing means the repository structure or pack data failed verification. Run check first without data reads for structure, then with read-data subsets to localise damaged packs. Depending on what is damaged, rebuild the index, remove a bad pack and re-backup its snapshots, or copy healthy snapshots to a fresh repository.