{"record":{"id":"106cbcc6e5088d82","repo":"router-for-me/CLIProxyAPI","slug":"no-suitable-browser-found-on-linux-system","errorCode":null,"errorMessage":"no suitable browser found on Linux system","messagePattern":"no suitable browser found on Linux system","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"internal/browser/browser.go","lineNumber":65,"sourceCode":"func openURLPlatformSpecific(url string) error {\n\tvar cmd *exec.Cmd\n\n\tswitch runtime.GOOS {\n\tcase \"darwin\": // macOS\n\t\tcmd = exec.Command(\"open\", url)\n\tcase \"windows\":\n\t\tcmd = exec.Command(\"rundll32\", \"url.dll,FileProtocolHandler\", url)\n\tcase \"linux\":\n\t\t// Try common Linux browsers in order of preference\n\t\tbrowsers := []string{\"xdg-open\", \"x-www-browser\", \"www-browser\", \"firefox\", \"chromium\", \"google-chrome\"}\n\t\tfor _, browser := range browsers {\n\t\t\tif _, err := exec.LookPath(browser); err == nil {\n\t\t\t\tcmd = exec.Command(browser, url)\n\t\t\t\tbreak\n\t\t\t}\n\t\t}\n\t\tif cmd == nil {\n\t\t\treturn fmt.Errorf(\"no suitable browser found on Linux system\")\n\t\t}\n\tdefault:\n\t\treturn fmt.Errorf(\"unsupported operating system: %s\", runtime.GOOS)\n\t}\n\n\tlog.Debugf(\"Running command: %s %v\", cmd.Path, cmd.Args[1:])\n\terr := cmd.Start()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to start browser command: %w\", err)\n\t}\n\n\tlog.Debug(\"Successfully opened URL using platform-specific command\")\n\treturn nil\n}\n\n// IsAvailable checks if the system has a command available to open a web browser.\n// It verifies the presence of necessary commands for the current operating system.\n//","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/router-for-me/CLIProxyAPI/blob/78f0c4079e3e6273d65d03b5549cffc898703264/internal/browser/browser.go#L47-L83","documentation":"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.","triggerScenarios":"Running the OAuth/login flow on a Linux box (container, server, minimal WM) where none of the six browser-launcher commands exist.","commonSituations":"Docker/headless servers with no browser installed; distros without the xdg-utils package; stripped-down container images (distroless, alpine without a browser).","solutions":["Install a launcher: `apt install xdg-utils` (Debian/Ubuntu) or equivalent, so xdg-open is available","Install any listed browser (firefox, chromium, google-chrome) and ensure it is on PATH","For headless machines, skip browser opening and manually visit the printed verification URI on another device","Use flags like --no-browser when running the server/CLI so the flow does not attempt to open a browser"],"exampleFix":"# before: container has no browser\n$ docker run myapp cli-proxy-api --login\n# error: no suitable browser found on Linux system\n\n# after\n$ apt-get update && apt-get install -y xdg-utils\n# or run headless\n$ cli-proxy-api --login --no-browser","handlingStrategy":"validation","validationCode":"if !browser.IsAvailable() {\n    log.Info(\"no browser on this machine; open the verification URL manually:\")\n    log.Info(verificationURI)\n} else {\n    _ = browser.OpenURL(verificationURI)\n}","typeGuard":null,"tryCatchPattern":"if err := browser.OpenURL(verificationURI); err != nil {\n    if strings.Contains(err.Error(), \"no suitable browser\") {\n        log.Warnf(\"no browser found; visit manually: %s\", verificationURI)\n    } else {\n        return err\n    }\n}","preventionTips":["Call browser.IsAvailable() before attempting OpenURL and always print the URI as a manual fallback","Install xdg-utils in container images that run interactive login","Use --no-browser in headless deployments"],"tags":["browser","linux","headless","oauth"],"backgroundTag":null,"analyzedSha":"78f0c4079e3e6273d65d03b5549cffc898703264","analyzedAt":"2026-08-15T12:26:37.444Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}