{"record":{"id":"84dd8bc034fb0a4b","repo":"hashicorp/nomad","slug":"unknown-node","errorCode":null,"errorMessage":"Unknown node","messagePattern":"Unknown node","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/errors.go","lineNumber":76,"sourceCode":"\tErrTokenInvalid               = errors.New(errTokenInvalid)\n\tErrPermissionDenied           = errors.New(errPermissionDenied)\n\tErrJobRegistrationDisabled    = errors.New(errJobRegistrationDisabled)\n\tErrNoNodeConn                 = errors.New(errNoNodeConn)\n\tErrUnknownMethod              = errors.New(errUnknownMethod)\n\tErrUnknownNomadVersion        = errors.New(errUnknownNomadVersion)\n\tErrNodeLacksRpc               = errors.New(errNodeLacksRpc)\n\tErrMissingAllocID             = errors.New(errMissingAllocID)\n\tErrIncompatibleFiltering      = errors.New(errIncompatibleFiltering)\n\tErrMalformedChooseParameter   = errors.New(errMalformedChooseParameter)\n\n\t// ErrResultPaginatorCreation is returned by list RPC handlers when the\n\t// result paginator cannot be built, for example when the server cannot\n\t// evaluate a requested filter expression. api.ResultPaginatorErrorContent\n\t// duplicates its message so the CLI can match it without importing structs.\n\t// Keep the two in sync.\n\tErrResultPaginatorCreation = errors.New(errResultPaginatorCreation)\n\n\tErrUnknownNode = errors.New(ErrUnknownNodePrefix)\n\n\tErrDeploymentTerminalNoCancel    = errors.New(errDeploymentTerminalNoCancel)\n\tErrDeploymentTerminalNoFail      = errors.New(errDeploymentTerminalNoFail)\n\tErrDeploymentTerminalNoPause     = errors.New(errDeploymentTerminalNoPause)\n\tErrDeploymentTerminalNoPromote   = errors.New(errDeploymentTerminalNoPromote)\n\tErrDeploymentTerminalNoResume    = errors.New(errDeploymentTerminalNoResume)\n\tErrDeploymentTerminalNoUnblock   = errors.New(errDeploymentTerminalNoUnblock)\n\tErrDeploymentTerminalNoRun       = errors.New(errDeploymentTerminalNoRun)\n\tErrDeploymentTerminalNoSetHealth = errors.New(errDeploymentTerminalNoSetHealth)\n\tErrDeploymentRunningNoUnblock    = errors.New(errDeploymentRunningNoUnblock)\n\n\tErrCSIClientRPCIgnorable  = errors.New(\"CSI client error (ignorable)\")\n\tErrCSIClientRPCRetryable  = errors.New(\"CSI client error (retryable)\")\n\tErrCSIVolumeMaxClaims     = errors.New(\"volume max claims reached\")\n\tErrCSIVolumeUnschedulable = errors.New(\"volume is currently unschedulable\")\n\tErrCSIPluginInUse         = errors.New(\"plugin in use\")\n)\n","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/errors.go#L58-L94","documentation":"Indicates the node referenced by an RPC (allocation restart, GC, signal, pause, stats, etc.) does not exist in Nomad's state store. The HTTP API layer maps it (along with no-node-conn and unknown-allocation) to a 404 response.","triggerScenarios":"Calling allocRestart, allocGC, allocSignal, allocPauseGet, allocPauseSet, or allocStats with an allocation/node whose node ID is not registered; or after the node was reaped from state.","commonSituations":"Stale node IDs cached by automation, nodes removed after a cluster rebuild, typos in node IDs, or clients acting on data from a snapshot of a different cluster.","solutions":["List current nodes ('nomad node status') and use a valid Node ID.","Re-fetch the allocation to get its current NodeID before calling node-scoped RPCs.","Check you are targeting the correct cluster/region/agent.","If the node was decommissioned, recreate or re-register it before retrying."],"exampleFix":"// before\nclient.Nodes().Info(staleNodeID)\n// after\nnodes, _ := client.Nodes().List(nil)\n// verify staleNodeID exists in nodes before proceeding","handlingStrategy":"type-guard","validationCode":"// Pre-check the node exists:\nn, err := client.Nodes().Info(nodeID, nil)\nif err != nil { return fmt.Errorf(\"node %s not found\", nodeID) }","typeGuard":"func isUnknownNodeErr(err error) bool {\n    return structs.IsErrUnknownNode(err) || structs.IsErrNoNodeConn(err)\n}","tryCatchPattern":"rpcErr := doNodeRPC(...)\nif structs.IsErrUnknownNode(rpcErr) {\n    // treat as 404: refresh node list, do not retry blindly\n    return refreshAndLookupNode(nodeID)\n}","preventionTips":["Re-fetch allocations/nodes from the API rather than caching IDs long-term.","Filter out terminal/lost nodes before issuing node RPCs.","Confirm cluster/region targeting in multi-region setups."],"tags":["nodes","not-found","rpc","nomad"],"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"}