hashicorp/nomad · error

Failed to parse Serf advertise address: %v

Error message

Failed to parse Serf advertise address: %v

What it means

For server agents, AdvertiseAddrs.Serf is validated with normalizeAdvertise using the Serf bind address and Ports.Serf (skipped when server is disabled). Failure to parse or validate the Serf advertise address aborts startup with this error, wrapping the underlying cause.

Source

Thrown at command/agent/config.go:2422

	}

	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)
		}

		c.Client.NetworkInterface = parsed
	}

	return nil
}

// parseSingleInterfaceTemplate parses a go-sockaddr template and returns an

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set advertise_addrs.serf to a valid host:port on this node
2. Verify the hostname resolves locally and the IP is assigned to the node
3. Use the bind-derived default by removing the override if unsure
4. Check wrapped %v detail for the exact parse error

Example fix

// before
advertise_addrs { serf = "node-cluster-internal:8301" } # name unresolvable
// after
advertise_addrs { serf = "10.0.0.5:8301" }

if serverEnabled {
	host, port, err := net.SplitHostPort(cfg.AdvertiseAddrs.Serf)
	if err == nil {
		if net.ParseIP(host) == nil { _, _ = net.LookupHost(host) }
		_, _ = strconv.Atoi(port)
	}
}

When it happens

Trigger: advertise_addrs.serf set to an unresolvable host, invalid IP/port, or an address that normalizeAdvertise cannot merge with Ports.Serf; only evaluated when server.enabled = true.

Common situations: Advertise name resolving only via a DNS entry missing on the node; wrong interface IP after cloud instance restart; typos like 'serf:8301' where a host was expected.

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 Serf address: %v
• Failed to parse HTTP advertise address (%v, %v, %v, %v): %v
• Failed to parse RPC advertise address: %v
• Defaulting advertise to localhost is unsafe, please set adve
• Unable to parse default advertise address: %v

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