{"record":{"id":"668de0465cad4274","repo":"hashicorp/nomad","slug":"error-making-snapshot-v","errorCode":null,"errorMessage":"error making snapshot: %v","messagePattern":"error making snapshot: (.+?)","errorType":"http","errorClass":null,"httpStatus":500,"severity":"error","filePath":"command/agent/alloc_endpoint.go","lineNumber":516,"sourceCode":"\t\t}\n\t}\n\n\treturn reply, rpcErr\n}\n\nfunc (s *HTTPServer) allocSnapshot(allocID string, resp http.ResponseWriter, req *http.Request) (any, error) {\n\tvar secret string\n\ts.parseToken(req, &secret)\n\tif !s.agent.Client().ValidateMigrateToken(allocID, secret) {\n\t\treturn nil, structs.ErrPermissionDenied\n\t}\n\n\tallocFS, err := s.agent.Client().GetAllocFS(allocID)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(allocNotFoundErr)\n\t}\n\tif err := allocFS.Snapshot(resp); err != nil {\n\t\treturn nil, fmt.Errorf(\"error making snapshot: %v\", err)\n\t}\n\treturn nil, nil\n}\n\nfunc (s *HTTPServer) allocStats(allocID string, resp http.ResponseWriter, req *http.Request) (any, error) {\n\n\t// Build the request and parse the ACL token\n\ttask := req.URL.Query().Get(\"task\")\n\targs := cstructs.AllocStatsRequest{\n\t\tAllocID: allocID,\n\t\tTask:    task,\n\t}\n\ts.parse(resp, req, &args.QueryOptions.Region, &args.QueryOptions)\n\n\t// Determine the handler to use\n\tuseLocalClient, useClientRPC, useServerRPC := s.rpcHandlerForAlloc(allocID)\n\n\t// Make the RPC","sourceCodeStart":498,"sourceCodeEnd":534,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/alloc_endpoint.go#L498-L534","documentation":"This error is returned by the Nomad agent's allocSnapshot HTTP endpoint (command/agent/alloc_endpoint.go:516) when the filesystem snapshot of an allocation fails. After resolving the allocation's filesystem via AllocFS, the endpoint calls allocFS.Snapshot(resp) to stream a tar-style snapshot back to the client; any error from that snapshot operation is wrapped with this message. It means the alloc was found and reachable, but the underlying archive/stream operation against the client driver failed.","triggerScenarios":"Calling the client-facing HTTP API GET /v1/client/allocation/<allocID>/snapshot (via ClientAllocRequest -> allocSnapshot) when allocFS.Snapshot(resp) returns an error — e.g. the allocation's task driver cannot produce a filesystem snapshot, the alloc's files changed or vanished mid-archive, or the streaming response failed mid-write.","commonSituations":"Operator runs `nomad alloc fs <alloc> ...` snapshot-style access or tools that download an alloc's filesystem while the task is being restarted/rescheduled; the alloc's host volume or task directory was cleaned up concurrently; driver-level filesystem errors (permissions, disk full) during snapshot creation.","solutions":["Retry the snapshot request after confirming the allocation is still running (nomad alloc status <allocID>); transient races with restarts often resolve on a fresh attempt.","Check the Nomad client logs on the node running the alloc for the underlying driver/filesystem error reported at snapshot time.","Verify the task directory and any host volumes still exist on the client node and are readable by the Nomad agent.","If the alloc is terminal or was rescheduled, target the new allocation ID instead."],"exampleFix":"// before: snapshotting a possibly-stale alloc\nsnap, err := client.AllocFS().Snapshot(allocID)\n// after: verify alloc state first\nalloc, _, err := client.Allocations().Info(allocID, nil)\nif err != nil { return err }\nif alloc.ClientStatus != \"running\" { return fmt.Errorf(\"alloc %s is %s; cannot snapshot\", allocID, alloc.ClientStatus) }\nsnap, err := client.AllocFS().Snapshot(allocID)","handlingStrategy":"retry","validationCode":"alloc, _, err := client.Allocations().Info(allocID, nil)\nif err != nil { return err }\nif alloc.ClientStatus != \"running\" {\n    return fmt.Errorf(\"alloc %s not snapshot-able (status=%s)\", allocID, alloc.ClientStatus)\n}","typeGuard":null,"tryCatchPattern":"var snap io.ReadCloser\nfor attempt := 0; attempt < 3; attempt++ {\n    snap, err = client.AllocFS().Snapshot(allocID, nil)\n    if err == nil { break }\n    if strings.Contains(err.Error(), \"error making snapshot\") {\n        time.Sleep(time.Duration(attempt+1) * time.Second)\n        continue\n    }\n    return err\n}","preventionTips":["Check the allocation's ClientStatus is running before requesting a snapshot.","Avoid snapshotting allocs during known restarts/reschedules; prefer stable, long-running allocations.","Monitor client-node disk and permissions on task directories.","Log and inspect the wrapped inner error from the HTTP response to distinguish transient vs permanent failures."],"tags":["nomad","allocations","filesystem","snapshot","http-api"],"backgroundTag":"alloc-filesystem-snapshot-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"}