What causes "invalid pin: must be exactly 6 digits" in netbirdio/netbird?

Use exactly six digits: `--with-pin 123456`

invalid pin: must be exactly 6 digits

Error message

invalid pin: must be exactly 6 digits

What it means

The --with-pin value does not match pinRegexp (^\d{6}$): the PIN must be exactly six digits. The check runs only when a pin was supplied; an empty value means the flag was not used and is fine.

Source

Thrown at client/cmd/expose.go:123

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

func isProtocolValid(exposeProtocol string) bool {
	switch strings.ToLower(exposeProtocol) {
	case "http", "https", "tcp", "udp", "tls":
		return true
	default:

View on GitHub (pinned to 93e97f4bf1)

Solutions

Use exactly six digits: `--with-pin 123456`
For an arbitrary secret, use `--with-password <secret>` instead of --with-pin

Example fix

# before
netbird expose --with-pin s3cret 8080

# after
netbird expose --with-password s3cret 8080

Defensive patterns

Strategy: validation

Validate before calling

if pinFlag != "" && !regexp.MustCompile(`^\d{6}$`).MatchString(pinFlag) {
	log.Fatalf("pin must be exactly 6 digits, got %q (for arbitrary secrets use --with-password)", pinFlag)
}

Prevention

Reserve --with-pin for exactly six digits; anything else belongs in --with-password
Quote the value in scripts so shell splitting cannot alter it
Do not pad or truncate device PINs to fit; the format is fixed

When it happens

Trigger: `--with-pin 12345` (5 digits), `--with-pin 1234567` (7 digits), `--with-pin 12a456` (non-digit), `--with-pin '123 456'` (embedded space from shell splitting).

Common situations: Muscle memory from 4-digit device PINs; passing an alphanumeric password to --with-pin when --with-password was intended; quotes lost in scripts.

Related errors

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