{"record":{"id":"5e5b404d1e915094","repo":"tailscale/tailscale","slug":"unsupported-command-requires-a-gui-build-of-the-m","errorCode":null,"errorMessage":"unsupported command: requires a GUI build of the macOS client","messagePattern":"unsupported command: requires a GUI build of the macOS client","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/tailscale/cli/configure_apple.go","lineNumber":86,"sourceCode":"\t\tLongHelp:   \"The vpn-config set of commands provides a way to add or remove the Tailscale VPN configuration from the macOS settings. This is the entry that appears in System Settings > VPN.\",\n\t\tSubcommands: []*ffcli.Command{\n\t\t\t{\n\t\t\t\tName:       \"install\",\n\t\t\t\tShortUsage: \"tailscale configure mac-vpn install\",\n\t\t\t\tShortHelp:  \"Write the Tailscale VPN configuration to the macOS settings\",\n\t\t\t\tLongHelp:   \"This command writes the Tailscale VPN configuration to the macOS settings. This is the entry that appears in System Settings > VPN. If you are running the Standalone variant of the client, you'll also need to install the system extension separately (run `tailscale configure sysext activate`).\",\n\t\t\t\tExec:       requiresGUI,\n\t\t\t},\n\t\t\t{\n\t\t\t\tName:       \"uninstall\",\n\t\t\t\tShortUsage: \"tailscale configure mac-vpn uninstall\",\n\t\t\t\tShortHelp:  \"Delete the Tailscale VPN configuration from the macOS settings\",\n\t\t\t\tLongHelp:   \"This command removes the Tailscale VPN configuration from the macOS settings. This is the entry that appears in System Settings > VPN. If you are running the Standalone variant of the client, you'll also need to deactivate the system extension separately (run `tailscale configure sysext deactivate`).\",\n\t\t\t\tExec:       requiresGUI,\n\t\t\t},\n\t\t},\n\t\tExec: func(ctx context.Context, args []string) error {\n\t\t\treturn errors.New(\"unsupported command: requires a GUI build of the macOS client\")\n\t\t},\n\t}\n}\n\nfunc requiresStandalone(ctx context.Context, args []string) error {\n\treturn errors.New(\"unsupported command: requires the Standalone (.pkg installer) GUI build of the client\")\n}\n\nfunc requiresGUI(ctx context.Context, args []string) error {\n\treturn errors.New(\"unsupported command: requires a GUI build of the macOS client\")\n}\n","sourceCodeStart":68,"sourceCodeEnd":98,"githubUrl":"https://github.com/tailscale/tailscale/blob/cfe32b8be6a33f8e24fbc369cbfbf7c729d9e042/cmd/tailscale/cli/configure_apple.go#L68-L98","documentation":"In the non-GUI build of the macOS CLI, the `tailscale configure mac-vpn` tree (and its install/uninstall leaves, via requiresGUI) is compiled as stubs: the parent command's Exec returns 'requires a GUI build of the macOS client'. Writing/removing the VPN configuration in System Settings is done by the GUI variants (Mac App Store or Standalone .pkg) of the macOS client, so the plain CLI build can only point you there.","triggerScenarios":"Invoking `tailscale configure mac-vpn` (directly, or any path not overridden by a GUI-variant build) from a tailscale CLI binary compiled without the GUI integration code paths — e.g. a homebrew/go-installed CLI or the variantgo command-line build on macOS.","commonSituations":"Installing tailscale via Homebrew or `go install` on a Mac and expecting mac-vpn to work; scripting VPN setup with the standalone CLI; CI provisioning of Macs.","solutions":["Use the GUI client's bundled CLI instead: install Tailscale from the Mac App Store or the Standalone .pkg, then run the `tailscale` binary that ships with it","For the Standalone variant, the System Settings VPN entry also needs `tailscale configure sysext activate` (see the command's LongHelp)","If you maintain builds, compile the appropriate GUI variant that provides the real mac-vpn implementations"],"exampleFix":"# before (plain CLI build)\n$ tailscale configure mac-vpn install\nerror: unsupported command: requires a GUI build of the macOS client\n\n# after (Standalone .pkg install)\n$ /Applications/Tailscale.app/Contents/MacOS/Tailscale configure mac-vpn install","handlingStrategy":"validation","validationCode":"# Use the GUI build's CLI, not a plain/go-installed binary\nTS=/Applications/Tailscale.app/Contents/MacOS/Tailscale\n[ -x \"$TS\" ] || { echo 'install the Tailscale GUI client (App Store or .pkg) first'; exit 1; }\n\"$TS\" configure mac-vpn install","typeGuard":null,"tryCatchPattern":null,"preventionTips":["On macOS, use the CLI bundled with the GUI client for system-integration subcommands","Check which tailscale binary is first in PATH (type -a tailscale) before blaming the command","Keep mac-vpn/sysext provisioning steps documented as GUI-variant-only"],"tags":["macos","gui","cli","build-variant"],"backgroundTag":null,"analyzedSha":"cfe32b8be6a33f8e24fbc369cbfbf7c729d9e042","analyzedAt":"2026-08-15T19:58:31.583Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}