hashicorp/nomad · error

%w %s

Error message

%w %s

What it means

getNodeForRpc resolves the target node ID from the state store before node-scoped RPCs (GC, restart, signal, pause state). If no node with that ID exists, it returns structs.ErrUnknownNode wrapped with the node ID. The error tells the caller the node ID does not match any registered node.

Source

Thrown at nomad/util.go:88

	for i := 1; i < l; i++ {
		cur := inputs[i]
		if cur > max {
			max = cur
		}
	}
	return max
}

// getNodeForRpc returns a Node struct if the Node supports Node RPC. Otherwise
// an error is returned.
func getNodeForRpc(snap *state.StateSnapshot, nodeID string) (*structs.Node, error) {
	node, err := snap.NodeByID(nil, nodeID)
	if err != nil {
		return nil, err
	}

	if node == nil {
		return nil, fmt.Errorf("%w %s", structs.ErrUnknownNode, nodeID)
	}

	if err := nodeSupportsRpc(node); err != nil {
		return nil, err
	}

	return node, nil
}

var minNodeVersionSupportingRPC = version.Must(version.NewVersion("0.8.0-rc1"))

// nodeSupportsRpc returns a non-nil error if a Node does not support RPC.
func nodeSupportsRpc(node *structs.Node) error {
	rawNodeVer, ok := node.Attributes["nomad.version"]
	if !ok {
		return structs.ErrUnknownNomadVersion
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Run `nomad node status` and use an exact NodeID from that output
2. Check you are targeting the correct region/cluster (-region flag)
3. If the node was deregistered, restart the Nomad agent on it so it re-registers
4. Confirm the node ID passed is the node's ID, not an allocation ID

Example fix

// before
client.Nodes().Restart("a1b2c3") // alloc-style or stale ID

// after
nodes, _ := client.Nodes().List(nil)
nodeID := nodes[0].ID // exact ID from the API
client.Nodes().Restart(nodeID)

nodes, _, err := client.Nodes().List(nil)
if err != nil { return err }
valid := false
for _, n := range nodes {
    if n.ID == nodeID { valid = true; break }
}
if !valid { return fmt.Errorf("node %q is not registered in this cluster/region", nodeID) }

func nodeExists(nodes []*api.NodeListStub, id string) bool {
    for _, n := range nodes { if n.ID == id { return true } }
    return false
}

_, err := client.Nodes().Restart(nodeID, nil)
var nr *api.Node
classifier := func(err error) bool { return strings.Contains(err.Error(), structs.ErrUnknownNode.Error()) }
if classifier(err) { /* refresh node list, re-register node, or fix ID/region */ }

When it happens

Trigger: Any node RPC (ClientAllocations.Restart/Signal, System.GarbageCollect node-scoped, pause state calls) with a NodeID that is absent from the state store — node deregistered, wrong ID, or wrong region.

Common situations: Targeting a node that was garbage-collected after being down past the deregister interval; copy/paste of a node ID from another cluster or region; using an alloc ID instead of a node ID by mistake.

Related errors

• Unknown node
• Unknown node %q
• job not found
• variable not found
• no servers

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