{"record":{"id":"049bacf63c30666f","repo":"hashicorp/nomad","slug":"failed-checking-integrity-of-snapshot-v","errorCode":null,"errorMessage":"failed checking integrity of snapshot: %v","messagePattern":"failed checking integrity of snapshot: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"helper/snapshot/archive.go","lineNumber":232,"sourceCode":"\n\t\tcase \"state.bin\":\n\t\t\tif _, err := io.Copy(io.MultiWriter(snap, snapHash), archive); err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to read or write snapshot data: %v\", err)\n\t\t\t}\n\n\t\tcase \"SHA256SUMS\":\n\t\t\tif _, err := io.Copy(&shaBuffer, archive); err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to read snapshot hashes: %v\", err)\n\t\t\t}\n\n\t\tdefault:\n\t\t\treturn fmt.Errorf(\"unexpected file %q in snapshot\", hdr.Name)\n\t\t}\n\t}\n\n\t// Verify all the hashes.\n\tif err := hl.DecodeAndVerify(&shaBuffer); err != nil {\n\t\treturn fmt.Errorf(\"failed checking integrity of snapshot: %v\", err)\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":214,"sourceCodeEnd":237,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/snapshot/archive.go#L214-L237","documentation":"The SHA256 checksums recorded in the snapshot's SHA256SUMS file did not match the data actually read from meta.json and state.bin. The library throws this as the integrity check after unpacking the tar, to refuse restoring or copying a snapshot whose contents were altered or corrupted. Root causes inside DecodeAndVerify include hash mismatch, missing hash entries, or missing files.","triggerScenarios":"snapshot.Verify, CopySnapshot, or Restore on a snapshot where state.bin or meta.json bytes differ from when the snapshot was written: bit rot on disk, partial upload/download followed by padding, editing of archive contents, gzip corruption after the sums were read, or a hash-list entry for a file not present in the tar.","commonSituations":"Snapshots stored on failing disks or unreliable object storage; snapshots modified by backup agents; truncated-then-padded transfers; manually edited meta.json (e.g. to force-restore older data) which breaks the recorded hash.","solutions":["Treat the snapshot as corrupt: re-take it with nomad operator snapshot save from a healthy server or restore from a different verified backup.","Run sha256sum on meta.json/state.bin extracted from the archive and compare to SHA256SUMS to confirm which file is corrupted and rule out transfer issues.","Verify the complete snapshot with nomad operator snapshot inspect (or snapshot.Verify) on the source node before shipping it to the target cluster.","Never hand-edit snapshot contents; if metadata surgery is truly required, re-create the archive and its SHA256SUMS consistently (unsupported, do this only with vendor guidance)."],"exampleFix":"// before: blindly restoring a snapshot that was edited by hand\n// (meta.json changed so its SHA256 no longer matches SHA256SUMS)\nsnapshot.Restore(logger, editedSnapshot, r)\n\n// after: verify integrity first and abort on mismatch\nif _, err := snapshot.Verify(editedSnapshot); err != nil {\n    return fmt.Errorf(\"snapshot failed integrity check, use an unmodified copy: %w\", err)\n}\neditedSnapshot.Seek(0, 0)\nsnapshot.Restore(logger, editedSnapshot, r)","handlingStrategy":"try-catch","validationCode":"// Detect integrity failure before attempting a restore\nfunc integrityCheck(in io.Reader) error {\n    _, err := snapshot.Verify(in)\n    return err // nil means the SHA256SUMS all matched\n}","typeGuard":null,"tryCatchPattern":"meta, err := snapshot.CopySnapshot(in, dest)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed checking integrity of snapshot\") {\n        // checksum mismatch: snapshot contents altered/corrupt\n        log.Error(\"snapshot failed SHA256 integrity check; re-take snapshot, do not restore\")\n        return err // never fall back to restoring corrupt data\n    }\n    return err\n}","preventionTips":["Verify snapshots (snapshot.Verify) immediately after taking and again after any transfer.","Keep at least two independently stored backups and prefer the one that verifies.","Monitor storage media health on nodes holding snapshots.","Never modify meta.json/state.bin inside a snapshot archive."],"tags":["go","snapshot","integrity","checksum","corruption"],"backgroundTag":"checksum-mismatch","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}