{"record":{"id":"f1941459c918f008","repo":"hashicorp/nomad","slug":"node-not-found","errorCode":null,"errorMessage":"node not found","messagePattern":"node not found","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/node_endpoint.go","lineNumber":591,"sourceCode":"// BatchDeregister. The caller should have already authorized the request.\nfunc (n *Node) deregister(args *structs.NodeBatchDeregisterRequest,\n\treply *structs.NodeUpdateResponse,\n\traftApplyFn func() (any, uint64, error),\n) error {\n\t// Look for the node\n\tsnap, err := n.srv.fsm.State().Snapshot()\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tnodes := make([]*structs.Node, 0, len(args.NodeIDs))\n\tfor _, nodeID := range args.NodeIDs {\n\t\tnode, err := snap.NodeByID(nil, nodeID)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tif node == nil {\n\t\t\treturn fmt.Errorf(\"node not found\")\n\t\t}\n\t\tnodes = append(nodes, node)\n\t}\n\n\t// Commit this update via Raft\n\t_, index, err := raftApplyFn()\n\tif err != nil {\n\t\tn.logger.Error(\"raft message failed\", \"error\", err)\n\t\treturn err\n\t}\n\n\tfor _, node := range nodes {\n\t\tnodeID := node.ID\n\n\t\t// Clear the heartbeat timer if any\n\t\tn.srv.clearHeartbeatTimer(nodeID)\n\n\t\t// Create the evaluations for this node","sourceCodeStart":573,"sourceCodeEnd":609,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/node_endpoint.go#L573-L609","documentation":"Inside the shared deregister path, each NodeID is looked up in the state store; if any ID has no corresponding node entry, deregistration aborts with 'node not found'. The node was already removed or the ID never existed.","triggerScenarios":"Deregister/BatchDeregister called for a node ID absent from the snapshot — node previously deregistered, ID typo'd, or server state restored from an older snapshot.","commonSituations":"Double-execution of cleanup scripts (node already gone); deregistering after a server state restore; wrong cluster/region targeted.","solutions":["Verify the node exists via the nodes list API and use its exact UUID","Treat 'node not found' as already-deregistered success in idempotent cleanup scripts","Confirm you are querying the correct region/cluster","If the node should exist, check client connectivity — a stale client may have been garbage-collected"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"node, _, err := client.Nodes().Info(nodeID, nil)\nif err != nil || node == nil {\n    return nil // already gone; skip\n}","typeGuard":"func nodeExists(n *api.Node, err error) bool { return err == nil && n != nil }","tryCatchPattern":"err := client.Nodes().Deregister(nodeID, nil)\nif err != nil && strings.Contains(err.Error(), \"node not found\") {\n    return nil // idempotent success\n}","preventionTips":["Write deregistration scripts to be idempotent","Fetch exact UUIDs from the API before deregistering","Target the correct region/cluster"],"tags":["nomad","deregistration","not-found","idempotency"],"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"}