What causes "invalid port number: %s" in netbirdio/netbird?

Pass only the numeric local port: `netbird expose 8080`

invalid port number: %s

Error message

invalid port number: %s

What it means

The positional port argument to `netbird expose <port>` failed strconv.ParseUint(portStr, 10, 32): it is not an unsigned base-10 number. validateExposeFlags rejects it before any daemon connection is made.

Source

Thrown at client/cmd/expose.go:104

		if p := u[i+1:]; p != "" {
			return p
		}
	}
	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) {

View on GitHub (pinned to 93e97f4bf1)

Solutions

Pass only the numeric local port: `netbird expose 8080`
Select the protocol with the flag, not the argument: `netbird expose --protocol tcp 5432`
In scripts, guard the value: `[[ "$PORT" =~ ^[0-9]+$ ]] || { echo "bad port"; exit 1; }`

Example fix

# before
netbird expose tcp://localhost:5432

# after
netbird expose --protocol tcp 5432

Defensive patterns

Strategy: validation

Validate before calling

portRe := regexp.MustCompile(`^[0-9]{1,5}$`)
if !portRe.MatchString(portArg) {
	log.Fatalf("%q is not a numeric port; pass only the bare port, e.g. `netbird expose 8080`", portArg)
}

Prevention

Pass a bare decimal port, never host:port or a URL scheme
Select the protocol via --protocol, not by embedding it in the port argument
Guard variables in scripts before substitution: [[ "$PORT" =~ ^[0-9]+$ ]]

When it happens

Trigger: Passing 'localhost:8080', 'tcp://host:5432', '8080/tcp', '-80', '0x1F90', '80 80', or an empty string (unset $PORT variable) as the port argument.

Common situations: Copy-pasting a URL or docker-style host:port spec instead of a bare port; scripts passing an unset variable; whitespace or a unit suffix sneaking into the value.

Related errors

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