hashicorp/nomad · error

Error parsing advertise address %q: %v

Error message

Error parsing advertise address %q: %v

What it means

After template resolution, normalizeAdvertise() calls net.SplitHostPort on the advertise address. If that fails with an error other than a missing port or too many colons (e.g. an empty host), the address cannot be interpreted as host:port and this error wraps the underlying net error.

Source

Thrown at command/agent/config.go:2540

// If addr is not set and bind is a valid address, the returned string is the
// bind+port.
//
// If addr is not set and bind is not a valid advertise address, the hostname
// is resolved and returned with the port.
//
// Loopback is only considered a valid advertise address in dev mode.
func normalizeAdvertise(addr string, bind string, defport int, dev bool) (string, error) {
	addr, err := listenerutil.ParseSingleIPTemplate(addr)
	if err != nil {
		return "", fmt.Errorf("Error parsing advertise address template: %v", err)
	}

	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() {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set advertise to a plain form: bare IP ("10.0.0.5"), host:port ("10.0.0.5:8301"), or a resolvable hostname
2. Remove protocol prefixes, whitespace, or quotes embedded in the value
3. Check environment/config interpolation isn't producing an empty or malformed value
4. If using IPv6 literals, bracket them: "[::1]:8301"

Example fix

// before
advertise = "http://10.0.0.5"
// after
advertise = "10.0.0.5:8301"

if cfg.Advertise != "" {
    if _, _, err := net.SplitHostPort(cfg.Advertise); err != nil {
        return fmt.Errorf("invalid advertise %q: %w", cfg.Advertise, err)
    }
}

_, _, err := net.SplitHostPort(cfg.Advertise)
if err != nil && !isMissingPort(err) && !isTooManyColons(err) {
    cfg.Advertise = net.JoinHostPort(defaultIP, "8301")
}

When it happens

Trigger: advertise resolves to a string that is neither a valid host:port nor a bare host/IP — e.g. advertise = "" combined with failure paths, an address like ":8301" (missing host is allowed by SplitHostPort? no — host missing yields 'missing port' style errors only for port), or addresses like "host:" handled elsewhere; specifically errors like 'too many colons' are filtered out, so any other SplitHostPort failure triggers this.

Common situations: Setting advertise to a value with stray characters (spaces, protocol prefixes like http://), or config interpolation producing an empty/garbage string.

Related errors

• Error parsing advertise address template: %v
• Defaulting advertise to localhost is unsafe, please set adve
• Unable to parse default advertise address: %v
• no such consul cluster: %s
• nil consul config

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