{"record":{"id":"3d87b9c54a7920f8","repo":"netbirdio/netbird","slug":"resolve-w","errorCode":null,"errorMessage":"resolve: %w","messagePattern":"resolve: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/embed/embed.go","lineNumber":384,"sourceCode":"}\n\n// ListenTCP listens on the given address in the netbird network.\n// Not applicable if the userspace networking mode is disabled.\nfunc (c *Client) ListenTCP(address string) (net.Listener, error) {\n\tnsnet, addr, err := c.getNet()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\t_, port, err := net.SplitHostPort(address)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"split host port: %w\", err)\n\t}\n\tlistenAddr := net.JoinHostPort(addr.String(), port)\n\n\ttcpAddr, err := net.ResolveTCPAddr(\"tcp\", listenAddr)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"resolve: %w\", err)\n\t}\n\treturn nsnet.ListenTCP(tcpAddr)\n}\n\n// ListenUDP listens on the given address in the netbird network.\n// Not applicable if the userspace networking mode is disabled.\nfunc (c *Client) ListenUDP(address string) (net.PacketConn, error) {\n\tnsnet, addr, err := c.getNet()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\t_, port, err := net.SplitHostPort(address)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"split host port: %w\", err)\n\t}\n\tlistenAddr := net.JoinHostPort(addr.String(), port)\n","sourceCodeStart":366,"sourceCodeEnd":402,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/embed/embed.go#L366-L402","documentation":"Returned by Client.ListenTCP when net.ResolveTCPAddr rejects the address rebuilt as clientIP:port. Because the host is always the client's own valid overlay IP, failures come from the port side: a non-numeric port or a port outside 0..65535 after string manipulation.","triggerScenarios":"ListenTCP(\":99999\"), ListenTCP(\":http\") when the port name cannot be resolved via the system services database, or a port string with whitespace/signs.","commonSituations":"Computing the port as a string from an int that overflows 16 bits; using service names (\"https\") on minimal containers where /etc/services is absent; trailing whitespace in config-derived port strings.","solutions":["Use a numeric port in 0..65535.","Validate with net.ResolveTCPAddr(\"tcp\", net.JoinHostPort(\"0.0.0.0\", portStr)) or strconv.Atoi+range check before calling.","Trim whitespace on config-derived values."],"exampleFix":"// before\nln, err := client.ListenTCP(\":\" + cfg.Port) // cfg.Port = \"65536\"\n\n// after\nport, err := strconv.Atoi(strings.TrimSpace(cfg.Port))\nif err != nil || port < 0 || port > 65535 {\n    return fmt.Errorf(\"invalid port %q\", cfg.Port)\n}\nln, err := client.ListenTCP(fmt.Sprintf(\":%d\", port))","handlingStrategy":"validation","validationCode":"_, portStr, err := net.SplitHostPort(address)\nif err != nil { return err }\nport, err := strconv.ParseUint(portStr, 10, 16)\nif err != nil { return fmt.Errorf(\"port %q not numeric 0-65535\", portStr) }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use numeric ports only; avoid service-name ports for embedded listeners.","Range-check ports where they enter your config, not where they are used."],"tags":["network","validation","listen","embed"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}