{"record":{"id":"9f066a4524028291","repo":"hashicorp/nomad","slug":"raft-error-when-restoring-snapshot-v","errorCode":null,"errorMessage":"Raft error when restoring snapshot: %v","messagePattern":"Raft error when restoring snapshot: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/snapshot/snapshot.go","lineNumber":300,"sourceCode":"\tif err := read(decomp, &metadata, snap); err != nil {\n\t\treturn fmt.Errorf(\"failed to read snapshot file: %v\", err)\n\t}\n\n\tif err := concludeGzipRead(decomp); err != nil {\n\t\treturn err\n\t}\n\n\t// Sync and rewind the file so it's ready to be read again.\n\tif err := snap.Sync(); err != nil {\n\t\treturn fmt.Errorf(\"failed to sync temp snapshot: %v\", err)\n\t}\n\tif _, err := snap.Seek(0, 0); err != nil {\n\t\treturn fmt.Errorf(\"failed to rewind temp snapshot: %v\", err)\n\t}\n\n\t// Feed the snapshot into Raft.\n\tif err := r.Restore(&metadata, snap, 0); err != nil {\n\t\treturn fmt.Errorf(\"Raft error when restoring snapshot: %v\", err)\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":282,"sourceCodeEnd":305,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/snapshot/snapshot.go#L282-L305","documentation":"After preparing the temp file, Restore() hands the snapshot to the Raft store via r.Restore(&metadata, snap, 0). This error wraps any failure reported by the Raft layer while installing the snapshot — the snapshot metadata or contents were rejected by Raft.","triggerScenarios":"The Raft implementation's Restore returns an error, e.g. snapshot metadata with an index/term older than existing state, unsupported snapshot version, failure while the FSM applies the restore, or I/O errors while Raft persists the snapshot.","commonSituations":"Restoring an outdated snapshot onto a cluster that has already applied newer entries; version mismatch between the snapshot producer and consumer; FSM restore callbacks failing (e.g. corrupted state store); Raft log/snapshot storage problems on disk.","solutions":["Inspect the wrapped %v cause from the Raft layer for the precise rejection reason.","Ensure the snapshot is not older than the Raft state it is applied to (restore to a node/state at or before the snapshot's index).","Verify producer/consumer library and snapshot-format versions are compatible.","Re-export a fresh snapshot from a healthy leader and retry; check Raft/FSM logs for underlying storage errors."],"exampleFix":"// before\nerr := snapStore.Restore(staleSnapshotBytes) // Raft: snapshot is older than current state\n// after\nsnap := exportFreshSnapshotFromLeader(cluster)\nerr := snapStore.Restore(snap)","handlingStrategy":"validation","validationCode":"meta, err := snapshotVerify(data) // parse header/metadata first\nif err != nil { return err }\nif raftStore.LastIndex() > meta.Index {\n    return fmt.Errorf(\"snapshot index %d is behind raft state %d; refusing restore\", meta.Index, raftStore.LastIndex())\n}","typeGuard":null,"tryCatchPattern":"if err := snapStore.Restore(data); err != nil {\n    if strings.Contains(err.Error(), \"Raft error when restoring snapshot\") {\n        // surface wrapped cause; compare snapshot index/term against cluster state\n    }\n}","preventionTips":["Never restore a snapshot older than the target Raft state; take a fresh snapshot from the leader.","Keep snapshot-format versions aligned across cluster/library versions.","Verify FSM restore paths work in staging before disaster recovery.","Check Raft/FSM storage health (disk, WAL) before and after restore."],"tags":["raft","consensus","snapshot-restore","fsm"],"backgroundTag":"raft-snapshot-restore-rejected","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"}