router-for-me/CLIProxyAPI · warning

no suitable browser found on Linux system

Error message

no suitable browser found on Linux system

What it means

On Linux, browser.OpenURL walked a preference list (xdg-open, x-www-browser, www-browser, firefox, chromium, google-chrome) and none was found on PATH. Without any of these binaries the library cannot show the OAuth verification page, so it errors instead of silently doing nothing.

Source

Thrown at internal/browser/browser.go:65

func openURLPlatformSpecific(url string) error {
	var cmd *exec.Cmd

	switch runtime.GOOS {
	case "darwin": // macOS
		cmd = exec.Command("open", url)
	case "windows":
		cmd = exec.Command("rundll32", "url.dll,FileProtocolHandler", url)
	case "linux":
		// Try common Linux browsers in order of preference
		browsers := []string{"xdg-open", "x-www-browser", "www-browser", "firefox", "chromium", "google-chrome"}
		for _, browser := range browsers {
			if _, err := exec.LookPath(browser); err == nil {
				cmd = exec.Command(browser, url)
				break
			}
		}
		if cmd == nil {
			return fmt.Errorf("no suitable browser found on Linux system")
		}
	default:
		return fmt.Errorf("unsupported operating system: %s", runtime.GOOS)
	}

	log.Debugf("Running command: %s %v", cmd.Path, cmd.Args[1:])
	err := cmd.Start()
	if err != nil {
		return fmt.Errorf("failed to start browser command: %w", err)
	}

	log.Debug("Successfully opened URL using platform-specific command")
	return nil
}

// IsAvailable checks if the system has a command available to open a web browser.
// It verifies the presence of necessary commands for the current operating system.
//

View on GitHub (pinned to 78f0c4079e)

Solutions

1. Install a launcher: `apt install xdg-utils` (Debian/Ubuntu) or equivalent, so xdg-open is available
2. Install any listed browser (firefox, chromium, google-chrome) and ensure it is on PATH
3. For headless machines, skip browser opening and manually visit the printed verification URI on another device
4. Use flags like --no-browser when running the server/CLI so the flow does not attempt to open a browser

Example fix

# before: container has no browser
$ docker run myapp cli-proxy-api --login
# error: no suitable browser found on Linux system

# after
$ apt-get update && apt-get install -y xdg-utils
# or run headless
$ cli-proxy-api --login --no-browser

if !browser.IsAvailable() {
    log.Info("no browser on this machine; open the verification URL manually:")
    log.Info(verificationURI)
} else {
    _ = browser.OpenURL(verificationURI)
}

if err := browser.OpenURL(verificationURI); err != nil {
    if strings.Contains(err.Error(), "no suitable browser") {
        log.Warnf("no browser found; visit manually: %s", verificationURI)
    } else {
        return err
    }
}

When it happens

Trigger: Running the OAuth/login flow on a Linux box (container, server, minimal WM) where none of the six browser-launcher commands exist.

Common situations: Docker/headless servers with no browser installed; distros without the xdg-utils package; stripped-down container images (distroless, alpine without a browser).

Related errors

• failed to start browser command: %w
• missing access_token and refresh_token
• refresh response did not include access_token
• failed to save refreshed auth: %w
• antigravity token exchange: create request: %w

AI-assisted analysis of router-for-me/CLIProxyAPI@78f0c4079e (2026-08-15). Data as JSON: /api/errors/106cbcc6e5088d82. Report an issue: GitHub.