hashicorp/nomad · error

Failed to resolve Server RPC advertise address: %v

Error message

Failed to resolve Server RPC advertise address: %v

What it means

When no explicit Server RPC advertise address is configured, Nomad derives one from the Serf advertise IP (falling back to the memberlist BindAddr) joined with the client RPC port. It then resolves that host:port with net.ResolveTCPAddr; any resolution failure is wrapped in this error.

Source

Thrown at nomad/server.go:1247

	}
	if clientAddr.IP.IsUnspecified() {
		listener.Close()
		return fmt.Errorf("Client RPC advertise address is not advertisable: %v", clientAddr)
	}

	if s.config.ServerRPCAdvertise != nil {
		s.serverRpcAdvertise = s.config.ServerRPCAdvertise
	} else {
		// Default to the Serf Advertise + RPC Port
		serfIP := s.config.SerfConfig.MemberlistConfig.AdvertiseAddr
		if serfIP == "" {
			serfIP = s.config.SerfConfig.MemberlistConfig.BindAddr
		}

		addr := net.JoinHostPort(serfIP, fmt.Sprintf("%d", clientAddr.Port))
		resolved, err := net.ResolveTCPAddr("tcp", addr)
		if err != nil {
			return fmt.Errorf("Failed to resolve Server RPC advertise address: %v", err)
		}

		s.serverRpcAdvertise = resolved
	}

	// Verify that we have a usable advertise address
	serverAddr, ok := s.serverRpcAdvertise.(*net.TCPAddr)
	if !ok {
		return fmt.Errorf("Server RPC advertise address is not a TCP Address: %v", serverAddr)
	}
	if serverAddr.IP.IsUnspecified() {
		listener.Close()
		return fmt.Errorf("Server RPC advertise address is not advertisable: %v", serverAddr)
	}

	wrapper := tlsutil.RegionSpecificWrapper(s.config.Region, tlsWrap)
	s.raftLayer = NewRaftLayer(s.serverRpcAdvertise, wrapper)
	return nil

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix serf bind/advertise address in config to a valid IP or resolvable hostname
2. Set server_rpc advertise explicitly (advertise { rpc = "<ip>" }) so resolution of the Serf-derived address is bypassed
3. Verify DNS resolution on the host: `getent hosts <serfIP>` / check /etc/resolv.conf

Example fix

// before (server.hcl)
bind_addr = "my-host-internal"
// after
bind_addr = "0.0.0.0"
advertise {
  rpc = "10.0.2.15"
}

if _, err := net.ResolveTCPAddr("tcp", serfBindAddr+":0"); err != nil {
    return fmt.Errorf("serf bind addr %q unresolvable: %w", serfBindAddr, err)
}

if err := server.Setup(); err != nil {
    if strings.Contains(err.Error(), "Failed to resolve") {
        logger.Error("advertise address unresolvable; check DNS/bind_addr", "err", err)
    }
    return err
}

When it happens

Trigger: setupRPC(): serfIP falls back to s.config.SerfConfig.MemberlistConfig.BindAddr (e.g. a hostname or invalid string) and net.ResolveTCPAddr("tcp", "<serfIP>:<port>") returns an error such as DNS lookup failure or malformed address.

Common situations: serf bind_addr set to a hostname that fails DNS resolution; bind addr containing an interface name or invalid value; IPv6 literal mishandled; resolv.conf broken so the hostname cannot resolve.

Related errors

• no CNI network config found
• failed to initialize network configurator: %v
• network hostname %q is not a valid DNS name
• failed to configure networking for alloc: %v
• Client RPC advertise address is not advertisable: %v

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