hashicorp/nomad · error

Error parsing advertise address template: %v

Error message

Error parsing advertise address template: %v

What it means

normalizeAdvertise() runs the configured advertise address through listenerutil.ParseSingleIPTemplate, which processes Go/consul-template style templates like {{ GetPrivateIP }}. This error wraps any failure of that template parsing, meaning the advertise string contained template syntax that could not be evaluated or produced an invalid value.

Source

Thrown at command/agent/config.go:2532

	return addrs, err
}

// normalizeAdvertise returns a normalized advertise address.
//
// If addr is set, it is used and the default port is appended if no port is
// set.
//
// 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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check the advertise value in your config for typos in template function names and correct {{ }} syntax
2. Replace the template with a literal IP:port (e.g. advertise = "10.0.0.5:8301") to bypass template evaluation
3. Verify the node actually has an interface the template function can resolve (e.g. GetPrivateIP fails on hosts without one)
4. Update Consul if using a template function not supported by your version

Example fix

// before
advertise = "{{ GetPrviateIP }}"
// after
advertise = "{{ GetPrivateIP }}"

addr := os.Getenv("CONSUL_ADVERTISE")
if strings.Contains(addr, "{{") {
    if !strings.HasSuffix(strings.TrimSpace(addr), "}}") {
        return fmt.Errorf("advertise template braces unbalanced: %q", addr)
    }
}
// prefer a literal IP to skip template parsing entirely

addr, err := normalizeAdvertise(cfg.Advertise, cfg.BindAddr, 8301, dev)
if err != nil {
    if strings.Contains(err.Error(), "template") {
        log.Warn("advertise template failed, falling back to explicit IP")
        addr, err = normalizeAdvertise(myPrivateIP, cfg.BindAddr, 8301, dev)
    }
    if err != nil { return err }
}

When it happens

Trigger: The 'advertise' or 'advertise_reconnect_timeout' setting in the agent config contains a template expression (e.g. {{ GetPrivateInterfaces | attr "address" }}) that fails to parse or evaluate — malformed template syntax, an unknown template function, or a function returning no value.

Common situations: Copy-pasted template snippets from docs with typos ({{ GetPrviateIP }}), running Consul on a host with no routable private interface so a template function errors, or quoting issues in JSON/HCL config that mangle the braces.

Related errors

• Error parsing advertise address %q: %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/e9bb8630755e00be. Report an issue: GitHub.