{"record":{"id":"d8c4eb4846b5793a","repo":"hashicorp/nomad","slug":"unknown-node-q","errorCode":null,"errorMessage":"Unknown node %q","messagePattern":"Unknown node %q","errorType":"http","errorClass":null,"httpStatus":404,"severity":"error","filePath":"nomad/client_agent_endpoint.go","lineNumber":583,"sourceCode":"\treturn nil\n}\n\n// findClientConn is a helper that returns a connection to the client node or, if the client\n// is connected to a different server, a serverParts describing the server to which the\n// client bound RPC should be forwarded.\nfunc (a *Agent) findClientConn(nodeID string) (*nodeConnState, *peers.Parts, error) {\n\tsnap, err := a.srv.State().Snapshot()\n\tif err != nil {\n\t\treturn nil, nil, structs.NewErrRPCCoded(500, err.Error())\n\t}\n\n\tnode, err := snap.NodeByID(nil, nodeID)\n\tif err != nil {\n\t\treturn nil, nil, structs.NewErrRPCCoded(500, err.Error())\n\t}\n\n\tif node == nil {\n\t\terr := fmt.Errorf(\"Unknown node %q\", nodeID)\n\t\treturn nil, nil, structs.NewErrRPCCoded(404, err.Error())\n\t}\n\n\tif err := nodeSupportsRpc(node); err != nil {\n\t\treturn nil, nil, structs.NewErrRPCCoded(400, err.Error())\n\t}\n\n\t// Get the Connection to the client either by fowarding to another server\n\t// or creating direct stream\n\tstate, ok := a.srv.getNodeConn(nodeID)\n\tif ok {\n\t\treturn state, nil, nil\n\t}\n\n\t// Determine the server that has a connection to the node\n\tsrv, err := a.srv.serverWithNodeConn(nodeID, a.srv.Region())\n\tif err != nil {\n\t\tcode := 500","sourceCodeStart":565,"sourceCodeEnd":601,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/client_agent_endpoint.go#L565-L601","documentation":"findClientConn resolves the client RPC connection for a given node ID by looking the node up in the state store. If the node ID is unknown, it wraps this error in a 404 ErrRPCCoded response. It indicates the requested client node does not exist in the server's state.","triggerScenarios":"Calling forwardMonitorClient, forwardProfileClient, or Host targeting a client node whose NodeID is absent from the state store (snap.NodeByID returns nil).","commonSituations":"Node was deregistered/GC'd after inactivity; typo'd node ID; targeting a node in a different region/cluster; stale UI sessions referencing removed clients; running node against a cluster it never joined.","solutions":["Verify the node ID with `nomad node status` and use the exact ID of a registered client.","Re-register the client node (restart the nomad agent on the client) if it was GC'd.","Ensure you are querying the correct region where the node is registered."],"exampleFix":"// before\nconn, _, err := findClientConn(ctx, args, \"missing-node-id\") // 404 Unknown node\n// after\nnodes, _ := client.Nodes().List(nil)\nnodeID := pickExistingNode(nodes) // use a Node.ID from node status","handlingStrategy":"validation","validationCode":"node, _, err := client.Nodes().Info(nodeID, nil)\nif err != nil || node == nil {\n    return fmt.Errorf(\"node %s not registered; refresh node list\", nodeID)\n}","typeGuard":null,"tryCatchPattern":"conn, _, err := findClientConn(ctx, args, nodeID)\nvar rpcErr *structs.RPCError\nif errors.As(err, &rpcErr) && rpcErr.Code == 404 {\n    // node unknown: refresh node status and re-select a valid node\n}","preventionTips":["Resolve node IDs from `nomad node status` at call time, never from cached values.","Handle GC'd nodes by re-registering the client before agent RPCs.","Target nodes in the same region as the queried server."],"tags":["nomad","node","rpc","not-found","client-agent"],"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"}