hashicorp/nomad · warning

resp.Warning

Error message

resp.Warning

What it means

Agent.Join() sends a join request to a Consul agent; the agent's response can include a Warning field. If the agent reports a non-empty warning, Join returns it as an error (along with NumJoined). Unlike resp.Error, this indicates the join partially succeeded or completed with caveats the agent wants surfaced, e.g. joining by IP with LAN/WAN pool caveats.

Source

Thrown at api/agent.go:146

// more nodes have a successful result, no error is returned.
func (a *Agent) Join(addrs ...string) (int, error) {
	// Accumulate the addresses
	v := url.Values{}
	for _, addr := range addrs {
		v.Add("address", addr)
	}

	// Send the join request
	var resp joinResponse
	_, err := a.client.put("/v1/agent/join?"+v.Encode(), nil, &resp, nil)
	if err != nil {
		return 0, fmt.Errorf("failed joining: %s", err)
	}
	if resp.Error != "" {
		return 0, fmt.Errorf("failed joining: %s", resp.Error)
	}
	if resp.Warning != "" {
		return resp.NumJoined, errors.New(resp.Warning)
	}
	return resp.NumJoined, nil
}

// Members is used to query all of the known server members
func (a *Agent) Members() (*ServerMembers, error) {
	var resp *ServerMembers

	// Query the known members
	_, err := a.client.query("/v1/agent/members", &resp, nil)
	if err != nil {
		return nil, err
	}
	return resp, nil
}

// MembersOpts is used to query all of the known server members
// with the ability to set QueryOptions

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the returned error message: if it is a warning (e.g. about LAN/WAN address pools), the join likely succeeded — verify with Agent.Members().
2. Join using a resolvable hostname or the address appropriate for the intended network pool to avoid the ambiguity warning.
3. If automation must tolerate warnings, check the returned NumJoined > 0 and log the warning instead of aborting.

Example fix

// before
n, err := client.Agent().Join("10.0.0.5", false)
if err != nil {
    return err // aborts even though join succeeded with a warning
}
// after
n, err := client.Agent().Join("10.0.0.5", false)
if err != nil {
    if n > 0 {
        log.Warnf("join completed with warning: %v", err)
    } else {
        return err
    }
}

n, err := client.Agent().Join(addr, false)
if err != nil {
    if n > 0 {
        log.Warnf("join warning (NumJoined=%d): %v", n, err)
        return nil // treat as success but log
    }
    return err
}

When it happens

Trigger: Calling Agent.Join(addr) where the agent completes the join but sets resp.Warning — classically when joining with an IPv4/IPv6 address that maps to multiple network pools, or other non-fatal join conditions reported by the agent.

Common situations: Dual-stack (IPv4/IPv6) clusters where the join address is ambiguous between LAN and WAN gossip pools; scripted health checks that treat any non-nil error as failure even though NumJoined > 0.

Related errors

• contacted %d Nomad Servers: %v
• no one-time token returned
• no ACL token returned
• errMissingACLRoleID
• errMissingACLAuthMethodName

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