{"record":{"id":"980451cac967ba40","repo":"hashicorp/nomad","slug":"server-rpc-advertise-address-is-not-a-tcp-address","errorCode":null,"errorMessage":"Server RPC advertise address is not a TCP Address: %v","messagePattern":"Server RPC advertise address is not a TCP Address: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/server.go","lineNumber":1256,"sourceCode":"\t\t// Default to the Serf Advertise + RPC Port\n\t\tserfIP := s.config.SerfConfig.MemberlistConfig.AdvertiseAddr\n\t\tif serfIP == \"\" {\n\t\t\tserfIP = s.config.SerfConfig.MemberlistConfig.BindAddr\n\t\t}\n\n\t\taddr := net.JoinHostPort(serfIP, fmt.Sprintf(\"%d\", clientAddr.Port))\n\t\tresolved, err := net.ResolveTCPAddr(\"tcp\", addr)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to resolve Server RPC advertise address: %v\", err)\n\t\t}\n\n\t\ts.serverRpcAdvertise = resolved\n\t}\n\n\t// Verify that we have a usable advertise address\n\tserverAddr, ok := s.serverRpcAdvertise.(*net.TCPAddr)\n\tif !ok {\n\t\treturn fmt.Errorf(\"Server RPC advertise address is not a TCP Address: %v\", serverAddr)\n\t}\n\tif serverAddr.IP.IsUnspecified() {\n\t\tlistener.Close()\n\t\treturn fmt.Errorf(\"Server RPC advertise address is not advertisable: %v\", serverAddr)\n\t}\n\n\twrapper := tlsutil.RegionSpecificWrapper(s.config.Region, tlsWrap)\n\ts.raftLayer = NewRaftLayer(s.serverRpcAdvertise, wrapper)\n\treturn nil\n}\n\n// setupStreamingEndpoints is used to populate an RPC server with streaming\n// endpoints. This only gets called at server startup.\nfunc (s *Server) setupStreamingEndpoints(server *rpc.Server) {\n\t// The endpoints are client RPCs and don't include a connection\n\t// context. They also need to be registered as streaming endpoints in their\n\t// register() methods.\n","sourceCodeStart":1238,"sourceCodeEnd":1274,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/server.go#L1238-L1274","documentation":"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.","triggerScenarios":"setupRPC(): s.serverRpcAdvertise (from config.ServerRPCAdvertise or the resolved default) is not a *net.TCPAddr at the type assertion `s.serverRpcAdvertise.(*net.TCPAddr)`.","commonSituations":"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.","solutions":["Ensure config.ServerRPCAdvertise is set from net.ResolveTCPAddr (a *net.TCPAddr), not another net.Addr implementation","If embedding Nomad's server package in Go code, fix the value assigned to ServerRPCAdvertise","File a bug if this occurs with stock Nomad configuration, since config parsing normally yields TCPAddr"],"exampleFix":"// before (Go config setup)\ncfg.ServerRPCAdvertise, _ = net.ResolveUDPAddr(\"udp\", \"10.0.2.15:4647\")\n// after\ncfg.ServerRPCAdvertise, _ = net.ResolveTCPAddr(\"tcp\", \"10.0.2.15:4647\")","handlingStrategy":"type-guard","validationCode":"if adv, ok := cfg.ServerRPCAdvertise.(*net.TCPAddr); !ok || adv == nil {\n    return fmt.Errorf(\"ServerRPCAdvertise must be a *net.TCPAddr\")\n}","typeGuard":"func isTCPAddr(a net.Addr) (*net.TCPAddr, bool) {\n    ta, ok := a.(*net.TCPAddr)\n    return ta, ok\n}","tryCatchPattern":"if err := server.SetupRPC(ln); err != nil {\n    if strings.Contains(err.Error(), \"not a TCP Address\") {\n        logger.Error(\"advertise addr wrong type; use net.ResolveTCPAddr\", \"err\", err)\n    }\n    return err\n}","preventionTips":["Populate ServerRPCAdvertise only via net.ResolveTCPAddr","When embedding Nomad's server package, keep address types strict","Treat stock-config occurrences as bugs and check the config pipeline"],"tags":["network","type-assertion","configuration","nomad"],"backgroundTag":"wrong-address-type","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}