{"record":{"id":"2d27dd152b624fe3","repo":"hashicorp/nomad","slug":"node-not-found-s","errorCode":null,"errorMessage":"node not found: %s","messagePattern":"node not found: (.+?)","errorType":"http","errorClass":null,"httpStatus":500,"severity":"error","filePath":"command/agent/agent_endpoint.go","lineNumber":873,"sourceCode":"\tlookupNodeID := nodeID\n\tif serverID != \"\" {\n\t\tlookupNodeID = serverID\n\t}\n\n\t// The RPC endpoint actually forwards the request to the correct\n\t// agent, but we need to use the correct RPC interface.\n\tlocalClient, remoteClient, localServer := s.rpcHandlerForNode(lookupNodeID)\n\ts.logger.Debug(\"s.rpcHandlerForNode()\", \"lookupNodeID\", lookupNodeID, \"serverID\", serverID, \"nodeID\", nodeID, \"localClient\", localClient, \"remoteClient\", remoteClient, \"localServer\", localServer)\n\n\t// Make the RPC call\n\tif localClient {\n\t\trpcErr = s.agent.Client().ClientRPC(\"Agent.Host\", &args, &reply)\n\t} else if remoteClient {\n\t\trpcErr = s.agent.Client().RPC(\"Agent.Host\", &args, &reply)\n\t} else if localServer {\n\t\trpcErr = s.agent.Server().RPC(\"Agent.Host\", &args, &reply)\n\t} else {\n\t\trpcErr = fmt.Errorf(\"node not found: %s\", nodeID)\n\t}\n\n\treturn reply, rpcErr\n}\n\n// AgentSchedulerWorkerInfoRequest is used to query the running state of the\n// agent's scheduler workers.\nfunc (s *HTTPServer) AgentSchedulerWorkerInfoRequest(resp http.ResponseWriter, req *http.Request) (any, error) {\n\tsrv := s.agent.Server()\n\tif srv == nil {\n\t\treturn nil, CodedError(http.StatusBadRequest, ErrServerOnly)\n\t}\n\tif req.Method != http.MethodGet {\n\t\treturn nil, CodedError(http.StatusMethodNotAllowed, ErrInvalidMethod)\n\t}\n\n\tvar secret string\n\ts.parseToken(req, &secret)","sourceCodeStart":855,"sourceCodeEnd":891,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/agent_endpoint.go#L855-L891","documentation":"AgentHostRequest resolves which Nomad node owns the requested nodeID (local client, remote client via forwarding, or server). When the nodeID matches none of those — not this agent's client node, not any server — the handler has no target to RPC 'Agent.Host' to and returns 'node not found: <nodeID>'.","triggerScenarios":"GET /v1/agent/host?node_id=<id> where nodeID is a UUID that is neither the local Nomad client's node ID nor any server member's ID: stale/deleted node ID, wrong datacenter (no remote client path), or querying against a server-only agent with a client node's ID.","commonSituations":"Scripting host stats collection with a node ID captured before the client was restarted (new node ID generated); targeting a node in another region without server forwarding; typo'd node ID in an automation tool.","solutions":["Query `nomad node status` and use a current, valid node ID","Ensure the request goes to an agent in the same region/datacenter as the node, or to a server that can forward it","If targeting the local agent, omit node_id so the handler uses the local client's node","If the client was re-provisioned, re-register/look up its fresh node ID"],"exampleFix":"// before\ncurl http://localhost:4646/v1/agent/host?node_id=OLD-STALE-UUID\n// after\nNODE_ID=$(nomad node status -json | jq -r '.[0].ID')\ncurl http://localhost:4646/v1/agent/host?node_id=$NODE_ID","handlingStrategy":"validation","validationCode":"nodeID := \"...\" // from nomad node status\nif nodeID == \"\" || !uuidRegexp.MatchString(nodeID) {\n    return errors.New(\"invalid or missing node_id\")\n}","typeGuard":null,"tryCatchPattern":"resp, err := client.Agent().Host(nodeID, nil)\nif err != nil {\n    if strings.Contains(err.Error(), \"node not found\") {\n        // refresh node list and retry with a valid ID\n        nodes, _ := client.Nodes().List(nil)\n        ...\n    }\n    return err\n}","preventionTips":["Fetch node IDs live from `nomad node status`, never hardcode","Handle client re-provisioning: node IDs change on re-registration","Target the correct region/agent for the node"],"tags":["nomad","api","node","http-endpoint"],"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"}