What causes "invalid port number: must be between 1 and 65535" in netbirdio/netbird?

Choose a port in 1-65535 that the local service actually listens on

invalid port number: must be between 1 and 65535

Error message

invalid port number: must be between 1 and 65535

What it means

The port argument parsed as a number but is out of range: ParseUint succeeded and the value equals 0 or exceeds 65535. Rejected entirely client-side in validateExposeFlags.

Source

Thrown at client/cmd/expose.go:107

	}
	return strconv.FormatUint(uint64(fallback), 10)
}

// resolveExternalPort returns the effective external port, defaulting to the target port.
func resolveExternalPort(targetPort uint64) uint16 {
	if exposeExternalPort != 0 {
		return exposeExternalPort
	}
	return uint16(targetPort)
}

func validateExposeFlags(cmd *cobra.Command, portStr string) (uint64, error) {
	port, err := strconv.ParseUint(portStr, 10, 32)
	if err != nil {
		return 0, fmt.Errorf("invalid port number: %s", portStr)
	}
	if port == 0 || port > 65535 {
		return 0, fmt.Errorf("invalid port number: must be between 1 and 65535")
	}

	if !isProtocolValid(exposeProtocol) {
		return 0, fmt.Errorf("unsupported protocol %q: must be http, https, tcp, udp, or tls", exposeProtocol)
	}

	if isClusterProtocol(exposeProtocol) {
		if exposePin != "" || exposePassword != "" || len(exposeUserGroups) > 0 {
			return 0, fmt.Errorf("auth flags (--with-pin, --with-password, --with-user-groups) are not supported for %s protocol", exposeProtocol)
		}
	} else if cmd.Flags().Changed("with-external-port") {
		return 0, fmt.Errorf("--with-external-port is not supported for %s protocol", exposeProtocol)
	}

	if exposePin != "" && !pinRegexp.MatchString(exposePin) {
		return 0, fmt.Errorf("invalid pin: must be exactly 6 digits")
	}

View on GitHub (pinned to 93e97f4bf1)

Solutions

Choose a port in 1-65535 that the local service actually listens on
Discover the real port with `ss -ltnp` (Linux), `netstat -an | grep LISTEN`, or `lsof -i` and use that

Example fix

# before
netbird expose 65536

# after
netbird expose 8080

Defensive patterns

Strategy: validation

Validate before calling

port, err := strconv.ParseUint(portArg, 10, 32)
if err != nil || port < 1 || port > 65535 {
	log.Fatalf("port must be in 1..65535, got %q", portArg)
}

Prevention

Clamp user-supplied ports to 1-65535 before building the command
Verify the service's actual listening port with ss/netstat instead of guessing
Watch the 65536 off-by-one when incrementing a configured port

When it happens

Trigger: `netbird expose 0`, `netbird expose 65536`, `netbird expose 70000`, or any port-like number above the TCP/UDP limit.

Common situations: Off-by-one at the 65536 boundary; wrong port copied from documentation or notes; placeholder values like 99999 left in scripts.

Related errors

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