git-ecosystem/git-credential-manager · error · Exception

Failed to locate a utility to launch the default web…

Error message

Failed to locate a utility to launch the default web browser.

What it means

OpenBrowserInternal searches the system for a known 'shell execute' utility (xdg-open and similar, in the same order as the .NET Framework) to launch a URL. If none of the candidate utilities exist on PATH it throws, because there is no way to open the default browser.

Solutions

1. Install xdg-utils (e.g. `apt-get install xdg-utils` or `dnf install xdg-utils`) so xdg-open exists on PATH
2. Verify PATH inside the process includes the directory containing xdg-open (`which xdg-open`)
3. Open the URL manually on a headless machine instead of calling the browser-open API
4. Set BROWSER env var and provide a wrapper script if using a custom launcher

Example fix

// before
sessionManager.OpenBrowser(url); // throws on headless box
// after
if (TryFindOnPath("xdg-open", out _)) sessionManager.OpenBrowser(url);
else Console.WriteLine($"Open this URL manually: {url}");

static bool BrowserLauncherExists() =>
    new[]{"xdg-open","gnome-open","kde-open","wslview"}.Any(t =>
        Environment.GetEnvironmentVariable("PATH")!
            .Split(':').Any(dir => File.Exists(Path.Combine(dir, t))));

bool CanOpenBrowser() => TryGetShellExecuteHandler(out _);

try { sessionManager.OpenBrowser(url); }
catch (Exception ex) when (ex.Message.Contains("Failed to locate a utility")) { Console.WriteLine($"Open manually: {url}"); }

When it happens

Trigger: Calling the session manager's OpenBrowser (OpenBrowserInternal) on a Linux system where no browser-launch helper (xdg-open, gnome-open, kde-open, wslview, etc.) is installed or on PATH.

Common situations: Minimal/headless Linux images (containers, servers, slim distros) that lack xdg-utils; broken PATH in the process environment; stripped-down chroot or WSL without wslview.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Failed to open secret service session
• Browser authentication requires a desktop session
• Unable to persist credentials with the
• Can only use the ' ' credential store on Linux. See for…
• Cannot use the ' ' credential backing store without a…

AI-assisted analysis of git-ecosystem/git-credential-manager@e8ce762cd0 (2026-09-11). Data as JSON: /api/errors/d1df42c8613844c1. Report an issue: GitHub.

Appendix: source

Thrown at src/Core/Interop/Linux/LinuxSessionManager.cs:43

    protected override void OpenBrowserInternal(string url)
    {
        //
        // On Linux, 'shell execute' utilities like xdg-open launch a process without
        // detaching from the standard in/out descriptors. Some applications (like
        // Chromium) write messages to stdout, which is currently hooked up and being
        // consumed by Git, and cause errors.
        //
        // Sadly, the Framework does not allow us to redirect standard streams if we
        // set ProcessStartInfo::UseShellExecute = true, so we must manually launch
        // these utilities and redirect the standard streams manually.
        //
        // We try and use the same 'shell execute' utilities as the Framework does,
        // searching for them in the same order until we find one.
        //
        if (!TryGetShellExecuteHandler(Environment, out string shellExecPath))
        {
            throw new Exception("Failed to locate a utility to launch the default web browser.");
        }

        Trace.WriteLine($"Opening browser using '{shellExecPath}: {url}");

        var psi = new ProcessStartInfo(shellExecPath, url)
        {
            RedirectStandardOutput = true,
            // Ok to redirect stderr for non-git-related processes
            RedirectStandardError = true
        };

        Process.Start(psi);
    }

    private bool GetWebBrowserAvailable()
    {
        // We need a shell execute handler to be able to launch to browser
        if (!TryGetShellExecuteHandler(Environment, out _))

View on GitHub (pinned to e8ce762cd0)