hashicorp/nomad · error

Server RPC advertise address is not a TCP Address: %v

Error message

Server RPC advertise address is not a TCP Address: %v

What it means

After resolving the Server RPC advertise address, Nomad asserts it is a *net.TCPAddr before using it for the Raft layer. If s.serverRpcAdvertise holds some other net.Addr type, startup fails. This is a defensive invariant check on the advertise address pipeline.

Source

Thrown at nomad/server.go:1256

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

// setupStreamingEndpoints is used to populate an RPC server with streaming
// endpoints. This only gets called at server startup.
func (s *Server) setupStreamingEndpoints(server *rpc.Server) {
	// The endpoints are client RPCs and don't include a connection
	// context. They also need to be registered as streaming endpoints in their
	// register() methods.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Ensure config.ServerRPCAdvertise is set from net.ResolveTCPAddr (a *net.TCPAddr), not another net.Addr implementation
2. If embedding Nomad's server package in Go code, fix the value assigned to ServerRPCAdvertise
3. File a bug if this occurs with stock Nomad configuration, since config parsing normally yields TCPAddr

Example fix

// before (Go config setup)
cfg.ServerRPCAdvertise, _ = net.ResolveUDPAddr("udp", "10.0.2.15:4647")
// after
cfg.ServerRPCAdvertise, _ = net.ResolveTCPAddr("tcp", "10.0.2.15:4647")

if adv, ok := cfg.ServerRPCAdvertise.(*net.TCPAddr); !ok || adv == nil {
    return fmt.Errorf("ServerRPCAdvertise must be a *net.TCPAddr")
}

func isTCPAddr(a net.Addr) (*net.TCPAddr, bool) {
    ta, ok := a.(*net.TCPAddr)
    return ta, ok
}

if err := server.SetupRPC(ln); err != nil {
    if strings.Contains(err.Error(), "not a TCP Address") {
        logger.Error("advertise addr wrong type; use net.ResolveTCPAddr", "err", err)
    }
    return err
}

When it happens

Trigger: setupRPC(): s.serverRpcAdvertise (from config.ServerRPCAdvertise or the resolved default) is not a *net.TCPAddr at the type assertion `s.serverRpcAdvertise.(*net.TCPAddr)`.

Common situations: Rare in practice: programmatic/Go API misuse where ServerRPCAdvertise is populated with a non-TCPAddr (e.g. *net.UDPAddr) net.Addr implementation instead of a parsed *net.TCPAddr.

Related errors

• no CNI network config found
• failed to initialize network configurator: %v
• failed to configure networking for alloc: %v
• Client RPC advertise address is not advertisable: %v
• Failed to resolve Server RPC advertise address: %v

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