hashicorp/nomad · error

Failed to parse Serf address

Error message

Failed to parse Serf address %q: %v

What it means

Same resolution failure as RPC but for the Serf (gossip) bind address: net.ResolveTCPAddr cannot parse/resolve the configured Serf address, so the memberlist configuration cannot be built and server startup aborts.

Solutions

  1. Correct the Serf bind address in the server config
  2. Use a valid IP or resolvable hostname with a port
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at command/agent/agent.go:402 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class


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

Appendix: source

Thrown at command/agent/agent.go:402

	conf.JobMaxCount = jobMaxCount

	if agentConfig.Server.JobTrackedVersions != nil {
		if *agentConfig.Server.JobTrackedVersions <= 0 {
			return nil, fmt.Errorf("job_tracked_versions must be greater than 0")
		}
		conf.JobTrackedVersions = *agentConfig.Server.JobTrackedVersions
	}

	conf.OIDCIssuer = agentConfig.Server.OIDCIssuer

	// Set up the bind addresses
	rpcAddr, err := net.ResolveTCPAddr("tcp", agentConfig.normalizedAddrs.RPC)
	if err != nil {
		return nil, fmt.Errorf("Failed to parse RPC address %q: %v", agentConfig.normalizedAddrs.RPC, err)
	}
	serfAddr, err := net.ResolveTCPAddr("tcp", agentConfig.normalizedAddrs.Serf)
	if err != nil {
		return nil, fmt.Errorf("Failed to parse Serf address %q: %v", agentConfig.normalizedAddrs.Serf, err)
	}
	conf.RPCAddr.Port = rpcAddr.Port
	conf.RPCAddr.IP = rpcAddr.IP
	conf.SerfConfig.MemberlistConfig.BindPort = serfAddr.Port
	conf.SerfConfig.MemberlistConfig.BindAddr = serfAddr.IP.String()
	conf.SerfConfig.RejoinAfterLeave = agentConfig.Server.RejoinAfterLeave

	// Set up the advertise addresses
	rpcAddr, err = net.ResolveTCPAddr("tcp", agentConfig.AdvertiseAddrs.RPC)
	if err != nil {
		return nil, fmt.Errorf("Failed to parse RPC advertise address %q: %v", agentConfig.AdvertiseAddrs.RPC, err)
	}
	serfAddr, err = net.ResolveTCPAddr("tcp", agentConfig.AdvertiseAddrs.Serf)
	if err != nil {
		return nil, fmt.Errorf("Failed to parse Serf advertise address %q: %v", agentConfig.AdvertiseAddrs.Serf, err)
	}

	// Server address is the serf advertise address and rpc port. This is the

View on GitHub (pinned to 482b49bf1a)