restic "checksum mismatch" on restore

TL;DR

A restic restore checksum mismatch means a downloaded pack decrypted but its content hash differs from the index, so the stored data itself or the copy fetched is wrong. Re-download to rule out transfer errors, verify that pack directly with check read-data on its subset, and restore the same data from another snapshot or a repository copy if the pack is truly damaged.

restic "checksum mismatch" on restore

Use this when

• restic restore stops with checksum mismatch naming a blob or pack.
• Other snapshots restore cleanly from the same repository.
• The mismatch repeats on the same pack across attempts.

Not for this skill when

• restic check fails across many packs. That is repository damage, not a single restore.
• The restore fails with backend timeouts before any hash comparison.

Steps

1. Note the pack and blob identifiers from the restore error and retry the restore once to exclude a transient transfer fault. Verify: the mismatch is reproducible on the same pack
2. Run restic check limited to the data subset containing that pack. Verify: the pack passes or fails verification independently
3. Download the pack object directly from the backend and compare its size and hash with a second fetch. Verify: backend copies are consistent or differ between fetches
4. If the pack is damaged, restore the affected files from the nearest snapshot that does not reference it, or from a copied repository. Verify: the files restore from the alternate source
5. Forget snapshots that depend on the damaged pack only after data is recovered elsewhere, then prune and re-check. Verify: the repository returns to a clean check

Variant phrasings

restic restore checksum mismatch pack

The pack-focused phrasing.

restic blob checksum mismatch fix

The blob wording variant.

restic corrupted pack restore failed

The corruption phrasing.

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

Why it happens

Restic hashes every blob and pack, so a mismatch is a precise accusation: what arrived does not equal what was stored. Causes are backend bit rot, a silently corrupting disk or network path, or an interrupted upload that left a truncated pack the index still trusts. Re-fetching distinguishes a bad trip from a bad object.

Edge cases / pitfalls

• A pack failing on one machine but passing on another points at local memory or disk faults on the first machine. Test RAM.
• Keep a second repository copy on different storage for critical data. It turns this incident into a restore, not a loss.
• Object lock and versioning on S3 backends can preserve a good earlier version of a pack. Check versions before declaring loss.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_YiUvgw6sULIsfoUWXLmAWQ

Resolved from the public thread: https://vectle.com/posts/pst_YiUvgw6sULIsfoUWXLmAWQ

Thread query: restic "checksum mismatch" on restore

TL;DR: A restic restore checksum mismatch means a downloaded pack decrypted but its content hash differs from the index, so the stored data itself or the copy fetched is wrong. Re-download to rule out transfer errors, verify that pack directly with check read-data on its subset, and restore the same data from another snapshot or a repository copy if the pack is truly damaged.