{"record":{"id":"f756462ecacd26c3","repo":"hashicorp/nomad","slug":"failed-to-restore-from-snapshot-v","errorCode":null,"errorMessage":"failed to restore from snapshot: %v","messagePattern":"failed to restore from snapshot: (.+?)","errorType":"http","errorClass":null,"httpStatus":500,"severity":"critical","filePath":"nomad/operator_endpoint.go","lineNumber":698,"sourceCode":"\tif aclObj, err := op.srv.ResolveACL(&args); err != nil {\n\t\tcode := 500\n\t\tif err == structs.ErrTokenNotFound {\n\t\t\tcode = 400\n\t\t}\n\t\thandleFailure(code, err)\n\t\treturn\n\t} else if !aclObj.IsManagement() {\n\t\thandleFailure(403, structs.ErrPermissionDenied)\n\t\treturn\n\t}\n\n\top.srv.setQueryMeta(&reply.QueryMeta)\n\n\treader, errCh := decodeStreamOutput(decoder)\n\n\terr = snapshot.Restore(op.logger.Named(\"snapshot\"), reader, op.srv.raft)\n\tif err != nil {\n\t\thandleFailure(500, fmt.Errorf(\"failed to restore from snapshot: %v\", err))\n\t\treturn\n\t}\n\n\terr = <-errCh\n\tif err != nil {\n\t\thandleFailure(400, fmt.Errorf(\"failed to read stream: %v\", err))\n\t\treturn\n\t}\n\n\t// This'll be used for feedback from the leader loop.\n\ttimeoutCh := time.After(time.Minute)\n\n\tlerrCh := make(chan error, 1)\n\n\tselect {\n\t// Reassert leader actions and update all leader related state\n\t// with new state store content.\n\tcase op.srv.reassertLeaderCh <- lerrCh:","sourceCodeStart":680,"sourceCodeEnd":716,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/operator_endpoint.go#L680-L716","documentation":"Wraps an error from snapshot.Restore when the server fails to restore state from a streamed snapshot in snapshotRestore. This runs after decodeStreamOutput, meaning the stream decoded fine but applying it to Raft failed. Status 500 is returned to the client.","triggerScenarios":"snapshot.Restore returns an error while ingesting the decoded snapshot reader into op.srv.raft — e.g. corrupt snapshot data, incompatible snapshot version, or Raft apply failure.","commonSituations":"Restoring a snapshot taken from a different Nomad version into an older cluster; corrupted snapshot file from a failed download; Raft cluster quorum issues during restore.","solutions":["Verify the snapshot was produced by a Nomad version compatible with this server","Re-download/re-transfer the snapshot and checksum it before restoring again","Check Raft peer health and quorum on the target cluster","Review the wrapped error in logs to distinguish corruption vs version mismatch"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// inspect snapshot before restoring\nout, err := exec.Command(\"nomad\", \"operator\", \"snapshot\", \"inspect\", snapFile).CombinedOutput()\nif err != nil { return fmt.Errorf(\"invalid snapshot: %v: %s\", err, out) }","typeGuard":null,"tryCatchPattern":"err := client.Operator().SnapshotRestore(snapReader, nil, nil)\nif err != nil && strings.Contains(err.Error(), \"failed to restore from snapshot\") {\n    // check version compatibility and raft health before retry\n}","preventionTips":["Only restore snapshots from compatible Nomad versions","Checksum snapshots after transfer","Confirm raft quorum and stable leadership before restore"],"tags":["raft","snapshot","restore","state-store"],"backgroundTag":"snapshot-restore-failed","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"}