{"record":{"id":"1cd8a4564efa3c9a","repo":"hashicorp/nomad","slug":"allocation-not-found","errorCode":null,"errorMessage":"allocation not found","messagePattern":"allocation not found","errorType":"http","errorClass":null,"httpStatus":500,"severity":"error","filePath":"command/agent/alloc_endpoint.go","lineNumber":513,"sourceCode":"\tif rpcErr != nil {\n\t\tif structs.IsErrNoNodeConn(rpcErr) || structs.IsErrUnknownAllocation(rpcErr) || structs.IsErrUnknownNode(rpcErr) {\n\t\t\trpcErr = CodedError(404, rpcErr.Error())\n\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","sourceCodeStart":495,"sourceCodeEnd":531,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/alloc_endpoint.go#L495-L531","documentation":"allocSnapshot looks up the allocation's filesystem (GetAllocFS) on the local client to stream a snapshot of a file in the alloc dir. If GetAllocFS errors — the allocation is not hosted by this client node — it returns the 'allocation not found' sentinel (allocNotFoundErr).","triggerScenarios":"GET /v1/client/allocation/<alloc_id>/fs?path=... routed to a client node that does not run the allocation, with a migrate token that validates but the alloc FS is absent locally; deleted/GC'd allocation; wrong alloc ID routed via node_id targeting.","commonSituations":"Load balancer or script hitting the wrong Nomad client node for alloc file access; allocation garbage-collected after job stop while logs are still being fetched; stale alloc ID cached in tooling after rescheduling.","solutions":["Send the fs request to the node actually running the allocation (nomad alloc status -> Node ID), or use `nomad alloc fs` which resolves it","Check `nomad alloc status <alloc_id>` to confirm the allocation still exists and was not GC'd","If using node_id/query routing, verify the target client hosts that alloc","Re-fetch logs/files promptly; GC'd allocations are unrecoverable"],"exampleFix":"// before\ncurl http://wrong-node:4646/v1/client/allocation/abc123/fs?path=/logs/x\n// after\nnomad alloc status abc123   # find hosting node\nnomad alloc fs abc123 logs/app.log","handlingStrategy":"try-catch","validationCode":"alloc, _, err := client.Allocations().Info(allocID, nil)\nif err != nil || alloc == nil {\n    return fmt.Errorf(\"allocation %s not found or GC'd\", allocID)\n}","typeGuard":null,"tryCatchPattern":"snap, err := getAllocSnapshot(allocID)\nif err != nil && strings.Contains(err.Error(), \"allocation not found\") {\n    // resolve hosting node and retry there, or fail gracefully\n    return redirectOr404(allocID)\n}","preventionTips":["Resolve the hosting node via `nomad alloc status` before direct client fs calls","Prefer `nomad alloc fs`/API which forwards instead of direct client HTTP","Fetch alloc files before job stop/GC deadline","Handle rescheduled allocs: IDs change; re-resolve after rescheduling"],"tags":["nomad","allocation","filesystem","api"],"backgroundTag":"resource-not-found","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"}