git-ecosystem/git-credential-manager · critical · Trace2Exception

Failed to start helper process

Error message

Failed to start helper process: {0} {1}

What it means

AuthenticationBase.InvokeHelperAsync launches a UI helper subprocess (git-credential-ui helper) via ChildProcess.Start. If the process cannot be started (returns null), it throws a Trace2Exception with the helper path and arguments so the failure appears in trace2 telemetry.

Solutions

  1. Reinstall/repair git-credential-manager so all helper binaries exist at the expected location.
  2. Check antivirus/EDR logs and whitelist the GCM helper executable.
  3. Run in a non-interactive-safe mode: set GCM_INTERACTIVE=never or use a credential store that avoids the UI helper.
  4. Verify the helper path printed in the message exists and is executable (chmod +x on Linux/macOS).

Example fix

// before: helper missing on headless system
export GCM_INTERACTIVE=auto
// after: disable UI helper spawning
export GCM_INTERACTIVE=never
# or provide terminal-only flow
export GIT_TERMINAL_PROMPT=1
Defensive patterns

Strategy: fallback

Validate before calling

test -x "$(command -v git-credential-manager)" && echo "install ok"

Try / catch

try { var cred = await InvokeHelperAsync(...); } catch (Trace2Exception ex) when (ex.Message.StartsWith("Failed to start helper process")) { /* fall back to terminal prompt or PAT-based auth */ }

Prevention

When it happens

Trigger: Calling any authentication flow that delegates to a UI helper (e.g. OAuth/browser or account picker) where ChildProcess.Start fails to spawn the executable at `path` with `args` — missing binary, wrong install layout, or OS spawn failure.

Common situations: Broken or partial GCM installation; antivirus blocking process spawn; unsupported environments (headless Linux with GUI helper configured); PATH/deployment issues after upgrades.

Related errors

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

Appendix: source

Thrown at src/Core/Authentication/AuthenticationBase.cs:55

                RedirectStandardOutput = true,
                RedirectStandardError = false, // Do not redirect stderr as tracing might be enabled
                UseShellExecute = false,
                StandardOutputEncoding = EncodingEx.UTF8NoBom,
            };

            Context.Trace.WriteLine($"Starting helper process: {path} {args}");

            // We flush the trace writers here so that the we don't stomp over the
            // authentication helper's messages.
            Context.Trace.Flush();

            var process = ChildProcess.Start(Context.Trace2, procStartInfo, Trace2ProcessClass.UIHelper);
            if (process is null)
            {
                var format = "Failed to start helper process: {0} {1}";
                var message = string.Format(format, path, args);

                throw new Trace2Exception(Context.Trace2, message, format);
            }

            // Kill the process upon a cancellation request
            ct.Register(() => process.Kill());

            // Write the standard input to the process if we have any to write
            if (standardInput is not null)
            {
                await standardInput.BaseStream.CopyToAsync(process.StandardInput.BaseStream, ct);
                process.StandardInput.Close();
            }

            IDictionary<string, string> resultDict = await process.StandardOutput.ReadDictionaryAsync(StringComparer.OrdinalIgnoreCase);

            await Task.Run(() => process.WaitForExit(), ct);
            int exitCode = process.ExitCode;

            if (exitCode != 0)

View on GitHub (pinned to e8ce762cd0)