{"record":{"id":"72dd0da880793e8f","repo":"hashicorp/nomad","slug":"failed-to-load-snapshot-from-archive-w","errorCode":null,"errorMessage":"Failed to load snapshot from archive: %w","messagePattern":"Failed to load snapshot from archive: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/raftutil/snapshot.go","lineNumber":59,"sourceCode":"\n\terr = fsm.RestoreWithFilter(r, filter)\n\tif err != nil {\n\t\treturn nil, nil, nil, fmt.Errorf(\"failed to restore from snapshot: %w\", err)\n\t}\n\n\tselect {\n\tcase err := <-errCh:\n\t\treturn nil, nil, nil, err\n\tcase meta := <-metaCh:\n\t\treturn fsm, fsm.State(), meta, nil\n\t}\n}\n\nfunc RedactSnapshot(srcFile *os.File) error {\n\tsrcFile.Seek(0, 0)\n\tfsm, store, meta, err := RestoreFromArchive(srcFile, nil)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"Failed to load snapshot from archive: %w\", err)\n\t}\n\n\titer, err := store.RootKeys(nil)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"Failed to query for root keys: %v\", err)\n\t}\n\n\tfor {\n\t\traw := iter.Next()\n\t\tif raw == nil {\n\t\t\tbreak\n\t\t}\n\t\trootKey := raw.(*structs.RootKey)\n\t\tif rootKey == nil {\n\t\t\tbreak\n\t\t}\n\t\tif len(rootKey.WrappedKeys) > 0 {\n\t\t\trootKey.KeyID = rootKey.KeyID + \" [REDACTED]\"","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/raftutil/snapshot.go#L41-L77","documentation":"RedactSnapshot wraps any failure from RestoreFromArchive, which parses the snapshot archive (tar.gz) and rebuilds the FSM and store. This means the input file could not be read as a valid Raft snapshot archive: bad format, corruption, unsupported structure, or unreadable content. The original error is preserved via %w for errors.As/Is inspection.","triggerScenarios":"Calling helper/raftutil.RedactSnapshot with a *os.File whose contents are not a valid snapshot archive: empty file, truncated download, non-snapshot file, corrupt tar/gz stream, or an archive missing required snapshot members (meta.json, state.bin, logs.dat).","commonSituations":"Operator redacts a snapshot that was copied incompletely (scp/ctl-c mid-transfer), a snapshot produced by an incompatible Consul version, a file that is actually a BoltDB raft.db rather than a snapshot archive, or a 0-byte file created by the CLI before writing.","solutions":["Verify the file is a complete, valid snapshot archive (gzip/tar readable; e.g. `tar tzf snapshot.tar`) and re-download/re-take the snapshot if not.","Check the wrapped error with errors.Unwrap to see the underlying cause (tar format, checksum, or FSM decode failure) and fix that specific issue.","Confirm the snapshot came from the same or compatible product version as the tool doing the redaction.","Ensure the file is seekable and readable: RestoreFromArchive seeks to 0 first; a closed or read-only fd will fail."],"exampleFix":"// before\nerr := raftutil.RedactSnapshot(f) // f is a truncated/partial snapshot\n\n// after\nif fi, serr := f.Stat(); serr == nil && fi.Size() == 0 {\n    return fmt.Errorf(\"snapshot file is empty; re-run consul snapshot save\")\n}\nerr := raftutil.RedactSnapshot(f)","handlingStrategy":"validation","validationCode":"func validateSnapshotFile(f *os.File) error {\n    fi, err := f.Stat()\n    if err != nil {\n        return err\n    }\n    if fi.Size() == 0 {\n        return fmt.Errorf(\"snapshot file is empty\")\n    }\n    // sniff gzip magic\n    br := bufio.NewReader(f)\n    magic, _ := br.Peek(2)\n    f.Seek(0, 0)\n    if len(magic) < 2 || magic[0] != 0x1f || magic[1] != 0x8b {\n        return fmt.Errorf(\"not a gzip snapshot archive\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"err := raftutil.RedactSnapshot(f)\nvar inner error\nif err != nil && errors.Unwrap(err) != nil {\n    inner = errors.Unwrap(err)\n    log.Printf(\"snapshot load failed: %v (cause: %v)\", err, inner)\n}","preventionTips":["Always verify snapshot archives with the producer tool's verify command (e.g. `consul snapshot inspect`) before redacting.","Check file size > 0 and gzip magic before passing to RedactSnapshot.","Use consistent versions between snapshot producer and redaction tool.","Avoid copying snapshots mid-transfer; compare checksums after download."],"tags":["raft","snapshot","corrupt-archive","go"],"backgroundTag":"snapshot-archive-corrupt","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"}