netbirdio/netbird · warning

auth flags (--with-pin, --with-password, --with-user-groups)

Error message

auth flags (--with-pin, --with-password, --with-user-groups) are not supported for %s protocol

What it means

HTTP-layer authentication flags (--with-pin, --with-password, --with-user-groups) were combined with a 'cluster' L4 protocol. isClusterProtocol returns true for tcp, udp, and tls, which forward raw byte streams through the proxy cluster, so there is no HTTP request layer in the proxy where a PIN, password, or SSO group check could run. validateExposeFlags rejects the combination up front.

Source

Thrown at client/cmd/expose.go:116

	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")
	}

	if cmd.Flags().Changed("with-password") && exposePassword == "" {
		return 0, fmt.Errorf("password cannot be empty")
	}

	if cmd.Flags().Changed("with-user-groups") && len(exposeUserGroups) == 0 {
		return 0, fmt.Errorf("user groups cannot be empty")
	}

	return port, nil

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Drop the auth flags for L4 protocols: `netbird expose --protocol tcp 5432`
2. If authentication is a hard requirement, either switch to --protocol http/https (the service itself must be HTTP) or enforce authentication inside the exposed application

Example fix

# before
netbird expose --protocol tcp --with-password s3cret 5432

# after
netbird expose --protocol tcp 5432

cluster := map[string]bool{"tcp": true, "udp": true, "tls": true}
hasAuth := pin != "" || password != "" || len(userGroups) > 0
if cluster[strings.ToLower(proto)] && hasAuth {
	log.Fatal("auth flags only apply to http/https; remove --with-pin/--with-password/--with-user-groups for tcp/udp/tls")
}

When it happens

Trigger: `netbird expose --protocol tcp --with-password secret 5432`, or the same combination with --with-pin or --with-user-groups for tcp, udp, or tls.

Common situations: Copy-pasting an HTTP example and only changing --protocol; assuming the PIN/password protects every protocol; wanting 'some auth' on a database port.

Related errors

• unsupported protocol %q: must be http, https, tcp, udp, or t
• --with-external-port is not supported for %s protocol
• invalid protocol: %w
• invalid port number: %s
• invalid port number: must be between 1 and 65535

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