What causes "Must provide the NodeID" in hashicorp/nomad?

Populate args.NodeID with a valid, non-empty node UUID before calling HasNodeConn

Must provide the NodeID

Error message

Must provide the NodeID

What it means

This error is raised by the Status API HasNodeConn RPC on the agent's status endpoint. It is a request-validation error returned when the caller sends a NodeConnRequest without populating NodeID, which the endpoint requires to look up the connection state of a specific Nomad client node.

Source

Thrown at nomad/status_endpoint.go:158

	reply.LastTerm, err = strconv.ParseUint(stats["last_log_term"], 10, 64)
	if err != nil {
		return fmt.Errorf("error parsing server's last_log_term value: %s", err)
	}

	return nil
}

// HasNodeConn returns whether the server has a connection to the requested
// Node.
func (s *Status) HasNodeConn(args *structs.NodeSpecificRequest, reply *structs.NodeConnQueryResponse) error {
	// note: we're intentionally throwing away any auth error here and only
	// authenticate so that we can measure rate metrics
	s.srv.Authenticate(s.ctx, args)
	s.srv.MeasureRPCRate("status", structs.RateMetricRead, args)

	// Validate the args
	if args.NodeID == "" {
		return errors.New("Must provide the NodeID")
	}

	state, ok := s.srv.getNodeConn(args.NodeID)
	if ok {
		reply.Connected = true
		reply.Established = state.Established
	}

	return nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Populate args.NodeID with a valid, non-empty node UUID before calling HasNodeConn
Look up the node ID first via the Nodes().List API if it is unknown
Fix upstream code that passes an empty/unset node identifier

Example fix

// before
reply, err := client.Status().HasNodeConn(&api.QueryOptions{})
// after
nodeID := "3f7c1b2a-..."
reply, err := client.Status().HasNodeConn(&api.QueryOptions{}) // ensure the RPC request carries NodeID = nodeID

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

func hasNodeID(nodeID string) bool { return nodeID != "" }

Try / catch

err := hasNodeConn(nodeID)
if err != nil && strings.Contains(err.Error(), "Must provide the NodeID") {
    // fix request args and retry once with a resolved node ID
    id, lerr := resolveNodeID()
    if lerr == nil { err = hasNodeConn(id) }
}

Prevention

Always resolve the node UUID via Nodes().List before calling HasNodeConn
Never build the request from unset config or environment variables without a check
Validate identifiers are non-empty at the call-site boundary

When it happens

Trigger: Calling the Status.HasNodeConn RPC with args.NodeID == "" — e.g. constructing the request without setting NodeID, or forwarding an empty node identifier from a caller-side lookup.

Common situations: A tool or script queries node connectivity but the node ID variable is empty because the node is unregistered or the lookup returned nothing; a plugin/automation builds the RPC from an unset config value.

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/7c5339f0395dae99. Report an issue: GitHub.