netbirdio/netbird · error

resolve: %w

Error message

resolve: %w

What it means

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.

Source

Thrown at client/embed/embed.go:384

}

// ListenTCP listens on the given address in the netbird network.
// Not applicable if the userspace networking mode is disabled.
func (c *Client) ListenTCP(address string) (net.Listener, error) {
	nsnet, addr, err := c.getNet()
	if err != nil {
		return nil, err
	}

	_, port, err := net.SplitHostPort(address)
	if err != nil {
		return nil, fmt.Errorf("split host port: %w", err)
	}
	listenAddr := net.JoinHostPort(addr.String(), port)

	tcpAddr, err := net.ResolveTCPAddr("tcp", listenAddr)
	if err != nil {
		return nil, fmt.Errorf("resolve: %w", err)
	}
	return nsnet.ListenTCP(tcpAddr)
}

// ListenUDP listens on the given address in the netbird network.
// Not applicable if the userspace networking mode is disabled.
func (c *Client) ListenUDP(address string) (net.PacketConn, error) {
	nsnet, addr, err := c.getNet()
	if err != nil {
		return nil, err
	}

	_, port, err := net.SplitHostPort(address)
	if err != nil {
		return nil, fmt.Errorf("split host port: %w", err)
	}
	listenAddr := net.JoinHostPort(addr.String(), port)

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Use a numeric port in 0..65535.
2. Validate with net.ResolveTCPAddr("tcp", net.JoinHostPort("0.0.0.0", portStr)) or strconv.Atoi+range check before calling.
3. Trim whitespace on config-derived values.

Example fix

// before
ln, err := client.ListenTCP(":" + cfg.Port) // cfg.Port = "65536"

// after
port, err := strconv.Atoi(strings.TrimSpace(cfg.Port))
if err != nil || port < 0 || port > 65535 {
    return fmt.Errorf("invalid port %q", cfg.Port)
}
ln, err := client.ListenTCP(fmt.Sprintf(":%d", port))

_, portStr, err := net.SplitHostPort(address)
if err != nil { return err }
port, err := strconv.ParseUint(portStr, 10, 16)
if err != nil { return fmt.Errorf("port %q not numeric 0-65535", portStr) }

When it happens

Trigger: ListenTCP(":99999"), ListenTCP(":http") when the port name cannot be resolved via the system services database, or a port string with whitespace/signs.

Common situations: 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.

Related errors

• split host port: %w
• parse address %s: %w
• invalid MTU: %w
• parse log level: %w
• invalid dns labels: %w

AI-assisted analysis of netbirdio/netbird@93e97f4bf1 (2026-08-16). Data as JSON: /api/errors/3d87b9c54a7920f8. Report an issue: GitHub.