netbirdio/netbird · warning

invalid interface name %s. Please use the prefix utun follow

Error message

invalid interface name %s. Please use the prefix utun followed by a number on MacOS. e.g., utun1 or utun199

What it means

parseInterfaceName enforces a macOS-specific rule: on darwin the WireGuard/utun system requires the tunnel interface name to start with the kernel's 'utun' prefix, and the suffix must be a number. On every other OS the function returns nil immediately, so this error can only be produced on macOS.

Source

Thrown at client/cmd/up.go:776

			if last == interfaceInputType && inputType == interfaceInputType {
				return fmt.Errorf("%s is not a valid input for %s. it should not contain two interface names", element, externalIPMapFlag)
			}
			last = inputType
		}
	}
	return nil
}

func parseInterfaceName(name string) error {
	if runtime.GOOS != "darwin" {
		return nil
	}

	if strings.HasPrefix(name, "utun") {
		return nil
	}

	return fmt.Errorf("invalid interface name %s. Please use the prefix utun followed by a number on MacOS. e.g., utun1 or utun199", name)
}

func validateElement(element string) (int, error) {
	if isValidIP(element) {
		return ipInputType, nil
	}
	validIface, err := isValidInterface(element)
	if err != nil {
		return invalidInputType, fmt.Errorf("unable to validate the network interface name, error: %s", err)
	}

	if validIface {
		return interfaceInputType, nil
	}

	return interfaceInputType, fmt.Errorf("invalid IP or network interface name not found")
}

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Use a utun-prefixed name with a numeric suffix, e.g. `--interface-name utun1`
2. Omit --interface-name on macOS and let the system assign the next free utun
3. Template flags per-OS in shared scripts

Example fix

# before
netbird up --interface-name wg0        # on macOS
# after
netbird up --interface-name utun1       # or omit the flag

if runtime.GOOS == "darwin" && !strings.HasPrefix(ifaceName, "utun") {
	return fmt.Errorf("interface %q must use the utun prefix on macOS", ifaceName)
}

When it happens

Trigger: Running `netbird up --interface-name wg0` (or any non-utun name) on macOS; also names like 'tun0' or 'netbird0'. Note only the 'utun' prefix is checked here, e.g. utun1, utun199.

Common situations: Reusing Linux-oriented commands or docs on a Mac; deployment scripts shared across platforms without per-OS values.

Related errors

• parse custom DNS address: %v
• setup login request: %v
• empty string is not a valid input for %s
• %s is not a valid input for %s. it should be formatted as "S
• %s is not a valid input for %s. it should be formatted as "I

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