{"record":{"id":"ee046ecbefc245df","repo":"slackhq/nebula","slug":"only-wildcard-address-supported-got-q-v","errorCode":null,"errorMessage":"only wildcard address supported, got %q %v","messagePattern":"only wildcard address supported, got %q (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"service/service.go","lineNumber":219,"sourceCode":"}\n\n// Dial dials the provided address\nfunc (s *Service) Dial(network, address string) (net.Conn, error) {\n\treturn s.DialContext(context.Background(), network, address)\n}\n\n// Listen listens on the provided address. Currently only TCP with wildcard\n// addresses are supported.\nfunc (s *Service) Listen(network, address string) (net.Listener, error) {\n\tif network != \"tcp\" && network != \"tcp4\" {\n\t\treturn nil, errors.New(\"only tcp is supported\")\n\t}\n\taddr, err := net.ResolveTCPAddr(network, address)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif addr.IP != nil && !bytes.Equal(addr.IP, []byte{0, 0, 0, 0}) {\n\t\treturn nil, fmt.Errorf(\"only wildcard address supported, got %q %v\", address, addr.IP)\n\t}\n\tif addr.Port == 0 {\n\t\treturn nil, errors.New(\"specific port required, got 0\")\n\t}\n\tif addr.Port < 0 || addr.Port >= math.MaxUint16 {\n\t\treturn nil, fmt.Errorf(\"invalid port %d\", addr.Port)\n\t}\n\tport := uint16(addr.Port)\n\n\tl := &tcpListener{\n\t\tport:   port,\n\t\ts:      s,\n\t\taddr:   addr,\n\t\taccept: make(chan net.Conn),\n\t}\n\n\ts.mu.Lock()\n\tdefer s.mu.Unlock()","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/service/service.go#L201-L237","documentation":"Service.Listen only accepts the wildcard IPv4 address 0.0.0.0 (or an unset IP). After net.ResolveTCPAddr succeeds, Listen rejects any resolved IP that is not all-zero bytes. It exists because the in-memory netstack listener binds per-port on the stack rather than per-specific-address.","triggerScenarios":"Calling Service.Listen(\"tcp\", \"127.0.0.1:8080\") or \"192.168.1.5:8080\" or an IPv6 wildcard \"[::]:8080\"; any non-nil addr.IP not equal to []byte{0,0,0,0} trips the check at service/service.go:219.","commonSituations":"Binding to localhost (127.0.0.1) as a habit from real servers; resolving a hostname that yields a concrete IP; passing \":8080\" through a helper that prepends a host; IPv6 wildcard \"::\" which is 16 zero bytes and fails the 4-byte comparison.","solutions":["Pass \"tcp\" plus a wildcard address such as \":8080\" or \"0.0.0.0:8080\".","Strip the host from your address before calling Listen, keeping only the port.","Use Listen(\"tcp\", \":%d\") with a numeric port instead of a resolved hostname."],"exampleFix":"// before\nl, err := svc.Listen(\"tcp\", \"127.0.0.1:8080\")\n// after\nl, err := svc.Listen(\"tcp\", \":8080\")","handlingStrategy":"validation","validationCode":"a, err := net.ResolveTCPAddr(network, address)\nif err != nil {\n    return err\n}\nif a.IP != nil && !a.IP.Equal(net.IPv4zero) {\n    return fmt.Errorf(\"this listener only supports wildcard bind, got %s\", a.IP)\n}","typeGuard":"func isWildcardTCPAddr(a *net.TCPAddr) bool {\n    return a.IP == nil || a.IP.Equal(net.IPv4zero)\n}","tryCatchPattern":"l, err := svc.Listen(network, address)\nif err != nil {\n    if strings.Contains(err.Error(), \"only wildcard address supported\") {\n        address = fmt.Sprintf(\":%d\", portOnly(address))\n        l, err = svc.Listen(network, address)\n    }\n    if err != nil {\n        return err\n    }\n}","preventionTips":["Always construct listen addresses as \":port\" rather than host:port for this library.","Never resolve hostnames before calling Listen — resolution yields concrete IPs.","Remember \"::\" and 127.0.0.1 both fail; only the 4-byte 0.0.0.0 / nil IP passes."],"tags":["network","gvisor","netstack","listen","bind-address"],"backgroundTag":"wildcard-address-only","analyzedSha":"dd8f660c0ac37903ec4080ca4d3c861ba9342ceb","analyzedAt":"2026-09-03T11:13:55.444Z","contentChangedAt":"2026-09-03T11:13:55.444Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}