{"record":{"id":"9e672b9cb38c4fc2","repo":"hashicorp/nomad","slug":"client-rpc-advertise-address-is-not-a-tcp-address","errorCode":null,"errorMessage":"Client RPC advertise address is not a TCP Address: %v","messagePattern":"Client RPC advertise address is not a TCP Address: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"nomad/server.go","lineNumber":1228,"sourceCode":"\ts.setupStreamingEndpoints(s.rpcServer)\n\n\tlistener, err := s.createRPCListener()\n\tif err != nil {\n\t\tlistener.Close()\n\t\treturn err\n\t}\n\n\tif s.config.ClientRPCAdvertise != nil {\n\t\ts.clientRpcAdvertise = s.config.ClientRPCAdvertise\n\t} else {\n\t\ts.clientRpcAdvertise = s.rpcListener.Addr()\n\t}\n\n\t// Verify that we have a usable advertise address\n\tclientAddr, ok := s.clientRpcAdvertise.(*net.TCPAddr)\n\tif !ok {\n\t\tlistener.Close()\n\t\treturn fmt.Errorf(\"Client RPC advertise address is not a TCP Address: %v\", clientAddr)\n\t}\n\tif clientAddr.IP.IsUnspecified() {\n\t\tlistener.Close()\n\t\treturn fmt.Errorf(\"Client RPC advertise address is not advertisable: %v\", clientAddr)\n\t}\n\n\tif s.config.ServerRPCAdvertise != nil {\n\t\ts.serverRpcAdvertise = s.config.ServerRPCAdvertise\n\t} else {\n\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 {","sourceCodeStart":1210,"sourceCodeEnd":1246,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/server.go#L1210-L1246","documentation":"During RPC listener setup, the server binds a client RPC listener and then verifies its advertised address is a usable *net.TCPAddr. If the type assertion fails (advertise address is not a concrete TCP address, e.g. unspecified or mis-derived), the listener is closed and NewServer fails with this error.","triggerScenarios":"NewServer where bind/advertise configuration resolves clientRpcAdvertise to something other than *net.TCPAddr — typically an address that couldn't be resolved to a concrete IP, or advertise configured to a hostname that yields an unusable value.","commonSituations":"bind_addr set to a hostname that doesn't resolve, advertise settings pointing at 0.0.0.0-style values, misconfigured NAT/advertise stanzas, or containers started before their network interface is available.","solutions":["Set an explicit, resolvable IP in bind_addr / advertise blocks (e.g. 10.0.0.5) instead of a hostname or wildcard.","Ensure the configured interface exists before the agent starts (network readiness ordering).","Check the resolved advertise address with `nomad node status` / agent logs and fix the config accordingly."],"exampleFix":"// before\nbind_addr = \"my-host-internal\"   // unresolved hostname\n// after\nbind_addr = \"192.168.1.10\"       // concrete, routable IP","handlingStrategy":"validation","validationCode":"ip := net.ParseIP(cfg.BindAddr)\nif ip == nil || ip.IsUnspecified() {\n    return fmt.Errorf(\"bind_addr %q must resolve to a concrete, routable IP\", cfg.BindAddr)\n}","typeGuard":"func isTCPAddr(a net.Addr) (*net.TCPAddr, bool) {\n    t, ok := a.(*net.TCPAddr)\n    return t, ok && !t.IP.IsUnspecified()\n}","tryCatchPattern":"srv, err := nomad.NewServer(cfg, logger)\nif err != nil && strings.Contains(err.Error(), \"not a TCP Address\") {\n    return fmt.Errorf(\"fix bind/advertise address config: %w\", err)\n}","preventionTips":["Use explicit IPs, not hostnames or 0.0.0.0, in bind_addr/advertise.","Wait for the node's network interface to be ready before agent start (cloud-init ordering).","Validate resolved addresses in a startup preflight script."],"tags":["network","advertise","startup","address"],"backgroundTag":"invalid-advertise-address","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"}