hashicorp/nomad · error

missing node ID

Error message

missing node ID

What it means

The GetClientAllocs RPC is used by Nomad clients to fetch their allocations, and requires the client to identify its node. The endpoint returns this error when the request's NodeID is an empty string, before doing any state lookup.

Source

Thrown at nomad/node_endpoint.go:1371

	if done, err := n.srv.forward("Node.GetClientAllocs", args, args, reply); done {
		// We have a valid node connection since there is no error from the
		// forwarded server, so add the mapping to cache the
		// connection and allow the server to send RPCs to the client.
		if err == nil && n.ctx != nil && n.ctx.NodeID == "" && !isForwarded {
			n.ctx.NodeID = args.NodeID
			n.srv.addNodeConn(n.ctx)
		}

		return err
	}
	n.srv.MeasureRPCRate("node", structs.RateMetricList, args)
	if authErr != nil {
		return structs.ErrPermissionDenied
	}
	defer metrics.MeasureSince([]string{"nomad", "client", "get_client_allocs"}, time.Now())

	if args.NodeID == "" {
		return errors.New("missing node ID")
	}

	node, err := n.srv.State().NodeByID(nil, args.NodeID)
	if err != nil {
		return err
	}

	if err := auth.AuthorizeSameNode(args.GetIdentity(), args.NodeID); err != nil {
		return err
	}

	if node != nil {
		// We have a valid node connection, so add the mapping to cache the
		// connection and allow the server to send RPCs to the client. We only
		// cache the connection if it is not being forwarded from another
		// server.
		if n.ctx != nil && n.ctx.NodeID == "" && !args.IsForwarded() {
			n.ctx.NodeID = args.NodeID

View on GitHub (pinned to 482b49bf1a)

Solutions

  1. Ensure the Nomad client's data_dir is intact so its node ID persists; regenerate by restarting the client if lost.
  2. If calling the API manually, supply the node ID (lookup via /v1/nodes) in the request.
  3. Check client logs for node ID generation errors and fix underlying disk/permission issues.

Example fix

// before
req := &structs.NodeClientAllocsRequest{}

// after
req := &structs.NodeClientAllocsRequest{NodeID: node.ID}
Defensive patterns

Strategy: validation

Validate before calling

if nodeID == "" {
  return errors.New("GetClientAllocs requires a non-empty NodeID")
}

Try / catch

if err := resp.Err(); err != nil && strings.Contains(err.Error(), "missing node ID") {
  // re-fetch node ID from /v1/nodes and retry once
  return retryWithResolvedNodeID()
}

Prevention

When it happens

Trigger: A Nomad client contacting the server whose Node ID has not been generated/persisted yet, or a malformed/custom API call to v1/client/allocs (or the internal GetClientAllocs RPC) omitting NodeID.

Common situations: Corrupted or wiped client data dir losing node ID; custom tooling calling the internal RPC directly without setting NodeID; client registration timing issues.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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