hashicorp/nomad · error

No path to node

Error message

No path to node

What it means

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).

Source

Thrown at nomad/structs/errors.go:61

	errDeploymentTerminalNoPause     = "can't pause terminal deployment"
	errDeploymentTerminalNoPromote   = "can't promote terminal deployment"
	errDeploymentTerminalNoResume    = "can't resume terminal deployment"
	errDeploymentTerminalNoUnblock   = "can't unblock terminal deployment"
	errDeploymentTerminalNoRun       = "can't run terminal deployment"
	errDeploymentTerminalNoSetHealth = "can't set health of allocations for a terminal deployment"
	errDeploymentRunningNoUnblock    = "can't unblock running deployment"
)

var (
	ErrNoLeader                   = errors.New(errNoLeader)
	ErrNotReadyForConsistentReads = errors.New(errNotReadyForConsistentReads)
	ErrNoRegionPath               = errors.New(errNoRegionPath)
	ErrTokenNotFound              = errors.New(errTokenNotFound)
	ErrTokenExpired               = errors.New(errTokenExpired)
	ErrTokenInvalid               = errors.New(errTokenInvalid)
	ErrPermissionDenied           = errors.New(errPermissionDenied)
	ErrJobRegistrationDisabled    = errors.New(errJobRegistrationDisabled)
	ErrNoNodeConn                 = errors.New(errNoNodeConn)
	ErrUnknownMethod              = errors.New(errUnknownMethod)
	ErrUnknownNomadVersion        = errors.New(errUnknownNomadVersion)
	ErrNodeLacksRpc               = errors.New(errNodeLacksRpc)
	ErrMissingAllocID             = errors.New(errMissingAllocID)
	ErrIncompatibleFiltering      = errors.New(errIncompatibleFiltering)
	ErrMalformedChooseParameter   = errors.New(errMalformedChooseParameter)

	// ErrResultPaginatorCreation is returned by list RPC handlers when the
	// result paginator cannot be built, for example when the server cannot
	// evaluate a requested filter expression. api.ResultPaginatorErrorContent
	// duplicates its message so the CLI can match it without importing structs.
	// Keep the two in sync.
	ErrResultPaginatorCreation = errors.New(errResultPaginatorCreation)

	ErrUnknownNode = errors.New(ErrUnknownNodePrefix)

	ErrDeploymentTerminalNoCancel    = errors.New(errDeploymentTerminalNoCancel)
	ErrDeploymentTerminalNoFail      = errors.New(errDeploymentTerminalNoFail)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the node is up: 'nomad node status' and check the agent process/heartbeat on the client host
2. Check network/firewall connectivity between server and client on the RPC ports
3. Reschedule or stop the allocation onto a healthy node instead of signaling the unreachable one
4. Retry after the client reconnects (heartbeat restores the server->client route)

Example fix

// before
curl -X POST "$NOMAD/v1/client/allocation/<alloc-id>/restart"  # 404 No path to node
// after
nomad node status  # find healthy node
nomad job promote <job>   # or: nomad alloc stop <alloc-id> to reschedule on a reachable node

node, _, err := client.Nodes().Info(alloc.NodeID, nil)
if err == nil && node.Status != "ready" {
    return fmt.Errorf("node %s is %s; cannot reach client", alloc.NodeID, node.Status)
}

func IsErrNoNodeConn(err error) bool {
    return structs.IsErrNoNodeConn(err)
}

err := client.Allocs().Signal(allocID, nil, nil)
var coded *api.CodedError
if structs.IsErrNoNodeConn(err) || (errors.As(err, &coded) && coded.Code() == 404) {
    // reschedule the allocation rather than retrying blindly
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Region %q: %v
• network namespace already exists but was misconfigured
• network already configured but not found in state
• no CNI network config found
• no servers

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/b4203cb4a58f2e64. Report an issue: GitHub.