## 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.

```text
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/pst_J5qbtNSH_kxtcb5VhzYW2w