hashicorp/nomad · error

Unable to parse default advertise address: %v

Error message

Unable to parse default advertise address: %v

What it means

As a last resort normalizeAdvertise() evaluates the built-in template {{ GetPrivateIP }} to pick the first private IP. This error wraps failure of that template evaluation, meaning Consul could not determine any usable private advertise address.

Source

Thrown at command/agent/config.go:2573

	// 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 }}")
	if err != nil {
		return "", fmt.Errorf("Unable to parse default advertise address: %v", err)
	}
	return normalizeAddrWithPort(addr, defport), nil
}

// isMissingPort returns true if an error is a "missing port" error from
// net.SplitHostPort.
func isMissingPort(err error) bool {
	// matches error const in net/ipsock.go
	const missingPort = "missing port in address"
	return err != nil && strings.Contains(err.Error(), missingPort)
}

// isTooManyColons returns true if an error is a "too many colons" error from
// net.SplitHostPort.
func isTooManyColons(err error) bool {
	// matches error const in net/ipsock.go
	const tooManyColons = "too many colons in address"
	return err != nil && strings.Contains(err.Error(), tooManyColons)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set advertise_addr explicitly to a valid routable IP — this bypasses the default entirely
2. Configure a non-loopback interface with a private IP on the host
3. Check network interface configuration (ip addr / ifconfig) before starting Consul
4. If no private IP is appropriate, advertise a public IP deliberately

Example fix

// before
// no advertise set on loopback-only host
// after
advertise_addr = "203.0.113.10"

ip, ok := firstPrivateIP()
if !ok {
    return errors.New("host has no private IP; configure advertise_addr manually")
}

if err := startAgent(); err != nil && strings.Contains(err.Error(), "default advertise") {
    ip := promptOrConfiguredIP()
    return startAgentWithAdvertise(net.JoinHostPort(ip, "8301"))
}

When it happens

Trigger: advertise unset, bind fallback failed or yielded no acceptable IP, and ParseSingleIPTemplate("{{ GetPrivateIP }}") errors — typically when the host has no private (RFC1918/global unicast, non-loopback) address.

Common situations: Loopback-only containers or minimal VMs without configured networking, unusual network setups where GetPrivateIP finds no candidate interface, running Consul on hosts with only link-local addresses.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Defaulting advertise to localhost is unsafe, please set adve
• Failed to parse HTTP advertise address (%v, %v, %v, %v): %v
• Failed to parse RPC advertise address: %v
• Failed to parse Serf advertise address: %v
• Error parsing advertise address template: %v

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