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

Failed to start gpg.

Error message

Failed to start gpg.

What it means

Gpg.DecryptFile launches the external gpg executable via the configured IProcessManager to decrypt a file. If the process fails to start at all (gpg.Start returns false), it throws Trace2Exception with this message. This is an environment problem, not a data problem.

Solutions

1. Install GnuPG (gpg) and verify `gpg --version` works in the same environment the app runs in.
2. Check the configured gpg executable path in settings (e.g. credential.gpg path config) and correct it.
3. Ensure PATH includes the gpg install directory for the service/account running the app.
4. Catch the Trace2Exception and surface an actionable 'install/configure gpg' message to the user.

// pre-flight check before calling DecryptFile
bool gpgAvailable = FindExecutable("gpg") is not null; // or resolve the configured path

try { plaintext = gpg.DecryptFile(path); }
catch (Trace2Exception ex) when (ex.Message == "Failed to start gpg.")
{ throw new InvalidOperationException("gpg is not installed or not on PATH; install GnuPG or fix the configured gpg path.", ex); }

When it happens

Trigger: Calling DecryptFile when the gpg binary is not installed, not on PATH, the configured GpgPath/program path is wrong, or the OS refuses to spawn the process.

Common situations: Clean machines or CI containers without GnuPG installed; incorrect gpg configuration path in settings; PATH differences between dev shell and service environment.

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

• GPG_TTY is not set; add `export GPG_TTY=$(tty)` to your…
• Unable to persist credentials with the
• Can only use the ' ' credential store on POSIX systems. See…
• GPG executable does not exist with path
• Failed to locate ' ' executable on the path.

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

Appendix: source

Thrown at src/Core/Gpg.cs:49

        public string DecryptFile(string path)
        {
            var psi = new ProcessStartInfo(_gpgPath, $"--batch --decrypt \"{path}\"")
            {
                UseShellExecute = false,
                RedirectStandardOutput = true,
                // Suppress verbose decryption messages
                // Ok to redirect stderr for non-Git-related processes
                RedirectStandardError = true,
            };

            PrepareEnvironment(psi);

            using (var gpg = _processManager.CreateProcess(psi))
            {
                if (!gpg.Start(Trace2ProcessClass.Other))
                {
                    throw new Trace2Exception(_trace2, "Failed to start gpg.");
                }

                gpg.WaitForExit();

                if (gpg.ExitCode != 0)
                {
                    string stdout = gpg.StandardOutput.ReadToEnd();
                    string stderr = gpg.StandardError.ReadToEnd();
                    var format = "Failed to decrypt file '{0}' with gpg. exit={1}, out={2}, err={3}";
                    var message = string.Format(format, path, gpg.ExitCode, stdout, stderr);
                    throw new Trace2Exception(_trace2, message, format);
                }

                return gpg.StandardOutput.ReadToEnd();
            }
        }

        public void EncryptFile(string path, string gpgId, string contents)

View on GitHub (pinned to e8ce762cd0)