hashicorp/nomad · error

Failed to parse RPC advertise address: %v

Error message

Failed to parse RPC advertise address: %v

What it means

During normalization, AdvertiseAddrs.RPC is validated with normalizeAdvertise against the RPC bind address and Ports.RPC. If the RPC advertise address cannot be parsed or validated (bad host, unresolvable name, invalid host:port), the agent refuses to start with this error.

Source

Thrown at command/agent/config.go:2414

	c.normalizedAddrs = &NormalizedAddrs{
		RPC:  normalizeAddrWithPort(c.Addresses.RPC, c.Ports.RPC),
		Serf: normalizeAddrWithPort(c.Addresses.Serf, c.Ports.Serf),
	}
	c.normalizedAddrs.HTTP = make([]string, len(httpAddrs))
	for i, addr := range httpAddrs {
		c.normalizedAddrs.HTTP[i] = normalizeAddrWithPort(addr, c.Ports.HTTP)
	}

	addr, err = normalizeAdvertise(c.AdvertiseAddrs.HTTP, httpAddrs[0], c.Ports.HTTP, c.DevMode)
	if err != nil {
		return fmt.Errorf("Failed to parse HTTP advertise address (%v, %v, %v, %v): %v", c.AdvertiseAddrs.HTTP, c.Addresses.HTTP, c.Ports.HTTP, c.DevMode, err)
	}
	c.AdvertiseAddrs.HTTP = addr

	addr, err = normalizeAdvertise(c.AdvertiseAddrs.RPC, c.Addresses.RPC, c.Ports.RPC, c.DevMode)
	if err != nil {
		return fmt.Errorf("Failed to parse RPC advertise address: %v", err)
	}
	c.AdvertiseAddrs.RPC = addr

	// Skip serf if server is disabled
	if c.Server != nil && c.Server.Enabled {
		addr, err = normalizeAdvertise(c.AdvertiseAddrs.Serf, c.Addresses.Serf, c.Ports.Serf, c.DevMode)
		if err != nil {
			return fmt.Errorf("Failed to parse Serf advertise address: %v", err)
		}
		c.AdvertiseAddrs.Serf = addr
	}

	// Skip network_interface evaluation if not a client
	if c.Client != nil && c.Client.Enabled && c.Client.NetworkInterface != "" {
		parsed, err := parseSingleInterfaceTemplate(c.Client.NetworkInterface)
		if err != nil {
			return fmt.Errorf("Failed to parse network-interface: %v", err)
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set advertise_addrs.rpc to a valid host:port bound to this node
2. Verify DNS resolution of the advertised name (dig/getent)
3. Confirm the IP exists on the machine (ip addr)
4. Remove any scheme or stray characters from the value

Example fix

// before
advertise_addrs { rpc = "10.0.0.99:8300" } # IP not on this node
// after
advertise_addrs { rpc = "10.0.0.5:8300" }

host, port, err := net.SplitHostPort(cfg.AdvertiseAddrs.RPC)
if err != nil { /* malformed */ }
if net.ParseIP(host) == nil {
	if _, err := net.LookupHost(host); err != nil { /* unresolvable */ }
}
_, err = strconv.Atoi(port)

When it happens

Trigger: advertise_addrs.rpc containing a hostname that fails to resolve, a malformed IP, an invalid port portion, or an empty value combined with an invalid bind fallback.

Common situations: Advertise address pointing at an IP not assigned to the node; copy-pasting values with trailing slashes or whitespace; port outside the allowed range; stale configs after node IP changes.

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

• Failed to parse HTTP advertise address (%v, %v, %v, %v): %v
• Failed to parse Serf advertise address: %v
• Defaulting advertise to localhost is unsafe, please set adve
• Unable to parse default advertise address: %v
• No addresses found, please configure one.

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