hashicorp/nomad · error

Error resolving bind address %q: %v

Error message

Error resolving bind address %q: %v

What it means

In normalizeAddr, when no explicit address is configured the code falls back to resolving the bind address via net.LookupIP; resolution failure (unresolvable hostname, no network) prevents computing the advertise address and aborts agent startup.

Source

Thrown at command/agent/config.go:2553

	if addr != "" {
		// Default to using manually configured address
		_, _, err = net.SplitHostPort(addr)
		if err != nil {
			if !isMissingPort(err) && !isTooManyColons(err) {
				return "", fmt.Errorf("Error parsing advertise address %q: %v", addr, err)
			}

			// missing port, append the default
			return normalizeAddrWithPort(addr, defport), nil
		}

		return ipaddr.NormalizeAddr(addr), nil
	}

	// Fallback to bind address first, and then try resolving the local hostname
	ips, err := net.LookupIP(bind)
	if err != nil {
		return "", fmt.Errorf("Error resolving bind address %q: %v", bind, err)
	}

	// Return the first non-localhost unicast address
	for _, ip := range ips {
		if ip.IsLinkLocalUnicast() || ip.IsGlobalUnicast() {
			return normalizeAddrWithPort(ip.String(), defport), nil
		}
		if ip.IsLoopback() {
			if dev {
				// loopback is fine for dev mode
				return normalizeAddrWithPort(ip.String(), defport), nil
			}
			return "", fmt.Errorf("Defaulting advertise to localhost is unsafe, please set advertise manually")
		}
	}

	// Bind is not localhost but not a valid advertise IP, use first private IP
	addr, err = listenerutil.ParseSingleIPTemplate("{{ GetPrivateIP }}")

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set advertise explicitly to a routable IP so the bind fallback is never used
2. Change bind to a literal IP address instead of a hostname
3. Fix DNS/hosts resolution for the hostname used in bind
4. Verify /etc/resolv.conf points at a reachable resolver

Example fix

// before
bind_addr = "my-node.internal" // unresolvable
// after
bind_addr = "0.0.0.0"
advertise_addr = "10.0.0.5"

if cfg.Advertise == "" && isHostname(cfg.BindAddr) {
    if ips, err := net.LookupIP(cfg.BindAddr); err != nil || len(ips) == 0 {
        return fmt.Errorf("bind %q not resolvable; set advertise explicitly", cfg.BindAddr)
    }
}

ips, err := net.LookupIP(bind)
if err != nil {
    ip := firstNonLoopbackLocalIP()
    if ip != nil { return useAdvertise(net.JoinHostPort(ip.String(), port)) }
    return err
}

When it happens

Trigger: advertise is unset and bind is set to a hostname (or a value like {{ ... }} that resolved to one) that net.LookupIP cannot resolve — no DNS record, /etc/hosts miss, or DNS server unreachable.

Common situations: Containers/VMs where the hostname isn't registered in DNS, bind set to a stale hostname after infrastructure changes, or offline/broken resolv.conf during startup.

Related errors

• Defaulting advertise to localhost is unsafe, please set adve
• Unable to parse default advertise address: %v
• error renewing the lease: %w
• failed to derive Consul token for task %s: %v
• failed to derive Consul token for service %s: %v

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