restic+"checksum+mismatch"+on+restore

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

Isolate the bad content before deleting anything: run a targeted verify on the affected snapshot, clear the local Kopia cache and verify again to rule out a poisoned cache, and check the repository storage health in parallel. A checksum mismatch means bytes Kopia read back do not hash to the content ID it expected, which can be one damaged blob, bad storage under the repository, or a bad cached copy. Restoring the same file from an earlier snapshot or a second repository copy is the recovery path once the scope is known.

kopia restore failed "error restoring: checksum mismatch"

Use this when

• kopia restore or snapshot verify fails with error restoring and a checksum mismatch.
• One snapshot or one folder fails while other snapshots verify cleanly.
• The repository sits on a NAS, USB disk or synced folder that had a recent fault.

Not for this skill when

• The repository will not connect at all. Fix repository connection and credentials first.
• A restore fails because the target path is in use or not writable. That is a target problem, not content integrity.

Steps

1. Record the exact content or blob identifier and snapshot from the failure output and run snapshot verify scoped to that snapshot, rather than a full repository verify that can take hours and blur the scope. Verify: the verify result names the same content or clears this snapshot
2. Rule out the local cache: clear the Kopia cache for this repository, reconnect, and rerun the same scoped verify, because a partial or corrupt cached blob makes healthy repository data look damaged. Verify: the result after clearing cache is recorded and differs or is confirmed identical
3. Check the repository storage directly: filesystem scrub or error logs for a local or NAS repository, SMART health for its disks, or provider integrity reports for cloud storage, looking for errors in the same time range as the backup that wrote the bad content. Verify: storage health is reported clean or a specific device fault is found
4. Test the scope across snapshots: verify a snapshot before and after the affected one and try restoring the same file from the earlier snapshot to a staging folder. One bad content usually affects a narrow backup window, while many snapshots failing points at storage wide damage. Verify: the boundary between good and bad snapshots is known
5. Recover the data from the good copy: restore the affected files from the last verified snapshot, or from a second repository if this data is replicated, and compare file sizes and application level checks after restore. Do not repair by deleting the mismatched blob before the recovery copy exists. Verify: the needed files are recovered from a verified source and open correctly
6. Only after recovery, run Kopia maintenance and a broader content verify on the repository, and replace or migrate repository storage that showed device errors. Schedule regular snapshot verify sampling so the next mismatch is found by a check, not by a restore under pressure. Verify: the broader verify completes and the repository is on storage with a clean health record

Why it happens

Kopia stores deduplicated, encrypted contents addressed by a hash, so reading data back and rehashing it detects any change in the stored bytes. A mismatch means the blob in repository storage, an incomplete upload that was later referenced, a faulty disk or NAS silently altering data, or a damaged local cache no longer matches the recorded hash. Encryption means Kopia cannot guess the correct bytes, so recovery always comes from another good copy: an earlier snapshot sharing good contents, or a replicated repository. Compatibility: Kopia 0.15 to 0.18 and KopiaUI backed repositories on filesystem, S3, Azure, GCS and WebDAV storage.

Variants and edge cases

checksum mismatch on one large file only

Large contents span several blobs, so a single failing content can affect one big archive or video while thousands of small files verify. Recover that file from the earlier snapshot and check storage in the window when its bad copy was written.

verify passes but restore still reports mismatch

That split points at the local cache or the restore target cache path rather than the repository. Clear the cache, restore to a different target disk, and check target disk health before condemning the repository.

many snapshots fail checksum after NAS event

Treat that as storage loss, not Kopia damage: freeze writes to that repository, recover what verifies from it, and rebuild on healthy storage with replication before resuming normal backups.

Provenance

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

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

Thread query: kopia restore failed "error restoring: checksum mismatch"

TL;DR: Isolate the bad content before deleting anything: run a targeted verify on the affected snapshot, clear the local Kopia cache and verify again to rule out a poisoned cache, and check the repository storage health in parallel. A checksum mismatch means bytes Kopia read back do not hash to the content ID it expected, which can be one damaged blob, bad storage under the repository, or a bad cached copy. Restoring the same file from an earlier snapshot or a second repository copy is the recovery path once the scope is known.

Not specified by the original author.

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.