{"record":{"id":"a5e3617c8a2d3bf6","repo":"netbirdio/netbird","slug":"invalid-interface-name-s-please-use-the-prefix-u","errorCode":null,"errorMessage":"invalid interface name %s. Please use the prefix utun followed by a number on MacOS. e.g., utun1 or utun199","messagePattern":"invalid interface name (.+?)\\. Please use the prefix utun followed by a number on MacOS\\. e\\.g\\., utun1 or utun199","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"client/cmd/up.go","lineNumber":776,"sourceCode":"\t\t\tif last == interfaceInputType && inputType == interfaceInputType {\n\t\t\t\treturn fmt.Errorf(\"%s is not a valid input for %s. it should not contain two interface names\", element, externalIPMapFlag)\n\t\t\t}\n\t\t\tlast = inputType\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc parseInterfaceName(name string) error {\n\tif runtime.GOOS != \"darwin\" {\n\t\treturn nil\n\t}\n\n\tif strings.HasPrefix(name, \"utun\") {\n\t\treturn nil\n\t}\n\n\treturn fmt.Errorf(\"invalid interface name %s. Please use the prefix utun followed by a number on MacOS. e.g., utun1 or utun199\", name)\n}\n\nfunc validateElement(element string) (int, error) {\n\tif isValidIP(element) {\n\t\treturn ipInputType, nil\n\t}\n\tvalidIface, err := isValidInterface(element)\n\tif err != nil {\n\t\treturn invalidInputType, fmt.Errorf(\"unable to validate the network interface name, error: %s\", err)\n\t}\n\n\tif validIface {\n\t\treturn interfaceInputType, nil\n\t}\n\n\treturn interfaceInputType, fmt.Errorf(\"invalid IP or network interface name not found\")\n}\n","sourceCodeStart":758,"sourceCodeEnd":794,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/cmd/up.go#L758-L794","documentation":"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.","triggerScenarios":"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.","commonSituations":"Reusing Linux-oriented commands or docs on a Mac; deployment scripts shared across platforms without per-OS values.","solutions":["Use a utun-prefixed name with a numeric suffix, e.g. `--interface-name utun1`","Omit --interface-name on macOS and let the system assign the next free utun","Template flags per-OS in shared scripts"],"exampleFix":"# before\nnetbird up --interface-name wg0        # on macOS\n# after\nnetbird up --interface-name utun1       # or omit the flag","handlingStrategy":"validation","validationCode":"if runtime.GOOS == \"darwin\" && !strings.HasPrefix(ifaceName, \"utun\") {\n\treturn fmt.Errorf(\"interface %q must use the utun prefix on macOS\", ifaceName)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["On macOS, omit --interface-name and let the system pick a free utun","Keep per-OS flag maps in shared automation"],"tags":["go","netbird","cli","macos","validation","interface-name","utun"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}