hashicorp/nomad · error

Server RPC advertise address is not advertisable: %v

Error message

Server RPC advertise address is not advertisable: %v

What it means

The Server RPC advertise address resolved to a *net.TCPAddr but its IP is unspecified (0.0.0.0 or ::). Nomad cannot publish an any-address to other servers/clients, so setupRPC() closes the listener and aborts startup.

Source

Thrown at nomad/server.go:1260

		}

		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.

	clientAllocs := NewClientAllocationsEndpoint(s)
	clientAllocs.register()

	fsEndpoint := NewFileSystemEndpoint(s)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set advertise { rpc = "<specific-routable-ip>" } in the server config
2. Ensure bind_addr is a concrete IP or that Serf advertise resolves to one so the derived address is not wildcard
3. Verify with `nomad server members` / node startup logs after fixing

Example fix

// before (server.hcl)
advertise {
  rpc = "0.0.0.0:4647"
}
// after
advertise {
  rpc = "10.0.2.15:4647"
}

srv, err := net.ResolveTCPAddr("tcp", advertiseRPC)
if err != nil || srv.IP.IsUnspecified() {
    return fmt.Errorf("server rpc advertise must be a specific IP, got %q", advertiseRPC)
}

func isAdvertisable(a net.Addr) bool {
    ta, ok := a.(*net.TCPAddr)
    return ok && ta != nil && !ta.IP.IsUnspecified()
}

if err := server.SetupRPC(ln); err != nil {
    if strings.Contains(err.Error(), "not advertisable") {
        logger.Error("set a specific IP in advertise { rpc }")
    }
    return err
}

When it happens

Trigger: setupRPC(): s.serverRpcAdvertise ends up with an unspecified IP — typically ServerRPCAdvertise configured as 0.0.0.0:<port>, or the Serf-derived address defaulting to 0.0.0.0 while ServerRPCAdvertise is unset and the fallback did not pick a concrete IP.

Common situations: advertise { rpc = "0.0.0.0" } in server.hcl; nodes with wildcard bind addresses and no explicit advertise; containerized deployments relying on defaults.

Related errors

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

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