{"record":{"id":"74d59e020ca1f2e1","repo":"hashicorp/nomad","slug":"unknown-node-q-74d59e","errorCode":null,"errorMessage":"Unknown node %q","messagePattern":"Unknown node %q","errorType":"exception","errorClass":null,"httpStatus":400,"severity":"error","filePath":"nomad/client_fs_endpoint.go","lineNumber":294,"sourceCode":"\tif aclObj, err := f.srv.ResolveACL(&args); err != nil {\n\t\thandleStreamResultError(err, nil, encoder)\n\t\treturn\n\t} else if !aclObj.AllowNsOp(alloc.Namespace, acl.NamespaceCapabilityReadFS) {\n\t\thandleStreamResultError(structs.ErrPermissionDenied, nil, encoder)\n\t\treturn\n\t}\n\n\tnodeID := alloc.NodeID\n\n\t// Make sure Node is valid and new enough to support RPC\n\tnode, err := snap.NodeByID(nil, nodeID)\n\tif err != nil {\n\t\thandleStreamResultError(err, new(int64(500)), encoder)\n\t\treturn\n\t}\n\n\tif node == nil {\n\t\terr := fmt.Errorf(\"Unknown node %q\", nodeID)\n\t\thandleStreamResultError(err, new(int64(400)), encoder)\n\t\treturn\n\t}\n\n\tif err := nodeSupportsRpc(node); err != nil {\n\t\thandleStreamResultError(err, new(int64(400)), encoder)\n\t\treturn\n\t}\n\n\t// Get the connection to the client either by forwarding to another server\n\t// or creating a direct stream\n\tvar clientConn net.Conn\n\tstate, ok := f.srv.getNodeConn(nodeID)\n\tif !ok {\n\t\t// Determine the Server that has a connection to the node.\n\t\tsrv, err := f.srv.serverWithNodeConn(nodeID, f.srv.Region())\n\t\tif err != nil {\n\t\t\tvar code *int64","sourceCodeStart":276,"sourceCodeEnd":312,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/client_fs_endpoint.go#L276-L312","documentation":"Thrown in the streaming filesystem RPC handler (stream) when the target nodeID does not exist in the server's node registry. The request cannot be forwarded to any client, so a 400 is returned to the streaming caller. It is the fs/stream flavor of \"unknown node\": the ID given is not a known Nomad client.","triggerScenarios":"Calling the filesystem stream API (used by `nomad alloc fs`) with a node ID that is not registered, or where the alloc's node lookup returned nil before the stream was established.","commonSituations":"Stale alloc IDs from a GC'd/removed job; node deregistered between listing allocs and streaming files; typo in node/alloc identifier in scripts; state trimmed on servers after node GC.","solutions":["Run `nomad node status` and confirm the node/alloc still exists; re-fetch a current alloc ID.","If the job's allocations were GC'd, re-run the job to get new allocations.","Check you are passing an alloc ID (not a job name without the -job flag) to the fs command.","If the node was removed intentionally, run the workload on an existing node."],"exampleFix":"// before\nnomad alloc fs <old-gc'd-alloc-id>\n// after\nnomad job status web | # get live alloc id\nnomad alloc fs <current-alloc-id>","handlingStrategy":"try-catch","validationCode":"alloc, _, err := client.Allocations().Info(allocID, nil)\nif err != nil {\n    return fmt.Errorf(\"alloc %s gone; refresh alloc list\", allocID)\n}\nnode, _, err := client.Nodes().Info(alloc.NodeID, nil)\nif err != nil || node == nil {\n    return fmt.Errorf(\"node %s unknown; re-run job\", alloc.NodeID)\n}","typeGuard":null,"tryCatchPattern":"if strings.Contains(err.Error(), \"Unknown node\") {\n    // refetch alloc/node IDs and retry once\n    allocs, _, _ := client.Allocations().List(nil)\n    _ = allocs\n}","preventionTips":["Never cache alloc/node IDs across job restarts or GC windows.","Handle job GC by re-listing allocations before fs access.","Disable overly aggressive job GC for jobs you still need to inspect."],"tags":["filesystem","streaming","nomad","unknown-node"],"backgroundTag":"unknown-node-id","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"}