{"record":{"id":"b4203cb4a58f2e64","repo":"hashicorp/nomad","slug":"no-path-to-node","errorCode":null,"errorMessage":"No path to node","messagePattern":"No path to node","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/errors.go","lineNumber":61,"sourceCode":"\terrDeploymentTerminalNoPause     = \"can't pause terminal deployment\"\n\terrDeploymentTerminalNoPromote   = \"can't promote terminal deployment\"\n\terrDeploymentTerminalNoResume    = \"can't resume terminal deployment\"\n\terrDeploymentTerminalNoUnblock   = \"can't unblock terminal deployment\"\n\terrDeploymentTerminalNoRun       = \"can't run terminal deployment\"\n\terrDeploymentTerminalNoSetHealth = \"can't set health of allocations for a terminal deployment\"\n\terrDeploymentRunningNoUnblock    = \"can't unblock running deployment\"\n)\n\nvar (\n\tErrNoLeader                   = errors.New(errNoLeader)\n\tErrNotReadyForConsistentReads = errors.New(errNotReadyForConsistentReads)\n\tErrNoRegionPath               = errors.New(errNoRegionPath)\n\tErrTokenNotFound              = errors.New(errTokenNotFound)\n\tErrTokenExpired               = errors.New(errTokenExpired)\n\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)","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/errors.go#L43-L79","documentation":"ErrNoNodeConn means the server has no RPC path to the Nomad client node needed to serve the request. It is returned by client-forwarding RPCs such as ClientGCRequest, allocRestart, allocGC, allocSignal, allocPauseGet, and allocPauseSet. The HTTP layer treats it as a not-found condition, translating it to a 404 via CodedError (command/agent/alloc_endpoint.go:277,326).","triggerScenarios":"Calling allocation lifecycle endpoints (restart, signal, GC, pause get/set) when the target allocation's node is unreachable: node agent is down, partitioned, or its connection was drained; ClientGCRequest cannot reach any node for node GC.","commonSituations":"Client agent crashed or host offline while allocations still registered; network partition between servers and client; node deregistered/drained but API consumers still referencing its allocations; stale allocation IDs from a dead node in automation scripts.","solutions":["Verify the node is up: 'nomad node status' and check the agent process/heartbeat on the client host","Check network/firewall connectivity between server and client on the RPC ports","Reschedule or stop the allocation onto a healthy node instead of signaling the unreachable one","Retry after the client reconnects (heartbeat restores the server->client route)"],"exampleFix":"// before\ncurl -X POST \"$NOMAD/v1/client/allocation/<alloc-id>/restart\"  # 404 No path to node\n// after\nnomad node status  # find healthy node\nnomad job promote <job>   # or: nomad alloc stop <alloc-id> to reschedule on a reachable node","handlingStrategy":"try-catch","validationCode":"node, _, err := client.Nodes().Info(alloc.NodeID, nil)\nif err == nil && node.Status != \"ready\" {\n    return fmt.Errorf(\"node %s is %s; cannot reach client\", alloc.NodeID, node.Status)\n}","typeGuard":"func IsErrNoNodeConn(err error) bool {\n    return structs.IsErrNoNodeConn(err)\n}","tryCatchPattern":"err := client.Allocs().Signal(allocID, nil, nil)\nvar coded *api.CodedError\nif structs.IsErrNoNodeConn(err) || (errors.As(err, &coded) && coded.Code() == 404) {\n    // reschedule the allocation rather than retrying blindly\n}","preventionTips":["Monitor node heartbeats and alert when clients go offline","Reschedule or stop allocations on unreachable nodes instead of direct client RPC","Verify server-to-client RPC port connectivity in network policy","Clean up stale allocations after node drains or host decommissioning"],"tags":["network","rpc","nomad","node-unreachable","http-404"],"backgroundTag":"no-path-to-node","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"}