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.

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
• antigravity token exchange: create request
• antigravity token exchange: decode response
• antigravity token exchange: execute request
• antigravity token exchange: read response

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

Appendix: 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)