hashicorp/nomad · error

http addr of node %q (%s) is not advertised

Error message

http addr of node %q (%s) is not advertised

What it means

In api/api.go:606, getNodeClientImpl fetches the node to find its advertised HTTPAddr and returns this error when node.HTTPAddr is empty — the Nomad client agent has not advertised an HTTP address, so there is no known endpoint to talk to directly on that node. NodeDownErr-style precondition check before building a node-scoped client.

Source

Thrown at api/api.go:606

}

// nodeLookup is the definition of a function used to lookup a node. This is
// largely used to mock the lookup in tests.
type nodeLookup func(nodeID string, q *QueryOptions) (*Node, *QueryMeta, error)

// getNodeClientImpl is the implementation of creating a API client for
// contacting a node. It takes a function to lookup the node such that it can be
// mocked during tests.
func (c *Client) getNodeClientImpl(nodeID string, timeout time.Duration, q *QueryOptions, lookup nodeLookup) (*Client, error) {
	node, _, err := lookup(nodeID, q)
	if err != nil {
		return nil, err
	}
	if node.Status == "down" {
		return nil, NodeDownErr
	}
	if node.HTTPAddr == "" {
		return nil, fmt.Errorf("http addr of node %q (%s) is not advertised", node.Name, nodeID)
	}

	var region string
	switch {
	case q != nil && q.Region != "":
		// Prefer the region set in the query parameter
		region = q.Region
	case c.config.Region != "":
		// If the client is configured for a particular region use that
		region = c.config.Region
	default:
		// No region information is given so use GlobalRegion as the default.
		region = GlobalRegion
	}

	// Get an API client for the node
	conf := c.config.ClientConfig(region, node.HTTPAddr, node.TLSEnabled)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the Nomad client agent is running and healthy on that node (nomad node status <id>)
2. Wait for/retry after node registration completes on fresh joins
3. Check client advertise configuration (client { ... }) so the agent advertises its HTTP address
4. Force a re-registration (restart the nomad agent on the client) if the node entry is stale
5. Fall back to server-routed APIs (e.g. via the server's proxy endpoints) if you cannot reach the node directly

Example fix

// before
nodeClient, err := client.GetNodeClient(nodeID) // fails on half-registered node
// after
node, _, _ := client.Nodes().Info(nodeID, nil)
if node.HTTPAddr == "" { return nil, fmt.Errorf("node %s not ready; retry after registration", nodeID) }
nodeClient, err := client.GetNodeClient(nodeID)

node, _, err := client.Nodes().Info(nodeID, nil)
if err != nil { return err }
if node.Status == "down" { return api.NodeDownErr }
if node.HTTPAddr == "" { return errors.New("node not fully registered yet; retry") }

func nodeReachable(n *api.Node) bool {
	return n != nil && n.Status != "down" && n.HTTPAddr != ""
}

nodeClient, err := client.GetNodeClient(nodeID)
if err != nil && strings.Contains(err.Error(), "is not advertised") {
	return retryWithBackoff(5*time.Second, 6, func() error { _, e := client.GetNodeClient(nodeID); return e })
}

When it happens

Trigger: Calling GetNodeClient/GetNodeClientWithTimeout(nodeID) for a node whose status is not "down" but whose HTTPAddr is empty — typically an incomplete registration or a node agent that never advertised its API address.

Common situations: Node recently joined and registration not complete; client agent configured with no bind address advertised (broken advertise settings); stale node entries after agent reinstall; querying a node in a partitioned/lossy cluster.

Related errors

• Error querying node: %w
• network address family must be one of: "", %q, %q
• network namespace already exists but was misconfigured
• network already configured but not found in state
• no CNI network config found

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