tailscale/tailscale · error

unsupported command: requires a GUI build of the macOS clien

Error message

unsupported command: requires a GUI build of the macOS client

What it means

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.

Source

Thrown at cmd/tailscale/cli/configure_apple.go:86

		LongHelp:   "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.",
		Subcommands: []*ffcli.Command{
			{
				Name:       "install",
				ShortUsage: "tailscale configure mac-vpn install",
				ShortHelp:  "Write the Tailscale VPN configuration to the macOS settings",
				LongHelp:   "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`).",
				Exec:       requiresGUI,
			},
			{
				Name:       "uninstall",
				ShortUsage: "tailscale configure mac-vpn uninstall",
				ShortHelp:  "Delete the Tailscale VPN configuration from the macOS settings",
				LongHelp:   "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`).",
				Exec:       requiresGUI,
			},
		},
		Exec: func(ctx context.Context, args []string) error {
			return errors.New("unsupported command: requires a GUI build of the macOS client")
		},
	}
}

func requiresStandalone(ctx context.Context, args []string) error {
	return errors.New("unsupported command: requires the Standalone (.pkg installer) GUI build of the client")
}

func requiresGUI(ctx context.Context, args []string) error {
	return errors.New("unsupported command: requires a GUI build of the macOS client")
}

View on GitHub (pinned to cfe32b8be6)

Solutions

1. 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
2. For the Standalone variant, the System Settings VPN entry also needs `tailscale configure sysext activate` (see the command's LongHelp)
3. If you maintain builds, compile the appropriate GUI variant that provides the real mac-vpn implementations

Example fix

# before (plain CLI build)
$ tailscale configure mac-vpn install
error: unsupported command: requires a GUI build of the macOS client

# after (Standalone .pkg install)
$ /Applications/Tailscale.app/Contents/MacOS/Tailscale configure mac-vpn install

# Use the GUI build's CLI, not a plain/go-installed binary
TS=/Applications/Tailscale.app/Contents/MacOS/Tailscale
[ -x "$TS" ] || { echo 'install the Tailscale GUI client (App Store or .pkg) first'; exit 1; }
"$TS" configure mac-vpn install

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Taildrive CLI commands are not supported when using the macO
• unsupported command: requires the Standalone (.pkg installer
• the GUI version of Tailscale on macOS runs in a macOS sandbo
• can't open the Tailscale page in App Store: %w, output: %s
• unmount %s: %w

AI-assisted analysis of tailscale/tailscale@cfe32b8be6 (2026-08-15). Data as JSON: /api/errors/5e5b404d1e915094. Report an issue: GitHub.