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

Cannot use the ' ' credential backing store without a…

Error message

Cannot use the '{StoreNames.SecretService}' credential backing store without a graphical interface present.
See {Constants.HelpUrls.GcmCredentialStores} for more information.

What it means

Within ValidateSecretService, GCM additionally requires an active desktop (graphical) session because the Secret Service is provided by a desktop keyring daemon over D-Bus. Headless Linux hosts (SSH sessions, containers, CI runners) have no such session, so this Exception is thrown even on Linux.

Solutions

1. Switch the credential store on headless hosts to 'gpg' (pass) or 'cache' which do not require a desktop session.
2. Use a credential helper backed by a file or environment-based token (e.g. GCM_PROVIDER=none + PAT in a store file).
3. If a desktop session is genuinely intended, run inside a logged-in graphical session so the keyring/D-Bus session bus is available.

Example fix

// before (CI runner env)
export GCM_CREDENTIAL_STORE=secretservice
// after
export GCM_CREDENTIAL_STORE=gpg
export GCM_CREDENTIAL_STORE_GPG_PASSWD_FILE=~/pass.gpg

// headless detection before configuring
if (!process.env.DISPLAY && !process.env.WAYLAND_DISPLAY && storeType === 'secretservice') {
  console.warn('No desktop session; secretservice store will fail. Use gpg or cache.');
}

try {
  // git operation with secretservice store
} catch (ex) {
  if (String(ex).includes('graphical interface')) {
    // switch to GCM_CREDENTIAL_STORE=gpg or cache and retry
  }
}

When it happens

Trigger: Configuring store=secretservice and running git from an SSH shell, systemd service, Docker container, or CI job where _context.SessionManager.IsDesktopSession is false.

Common situations: CI pipelines that inherit developer .gitconfig; Docker builds pushing to private registries via git; servers administered over SSH after migrating from a desktop machine.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• Failed to search for credentials
• Failed to unlock item
• Failed to store credentials
• -1
• Failed to erase credentials

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

Appendix: source

Thrown at src/Core/CredentialStore.cs:268

            }
        }

        private void ValidateSecretService()
        {
            if (!PlatformUtils.IsLinux())
            {
                var message = $"Can only use the '{StoreNames.SecretService}' credential store on Linux.";
                _context.Trace2.WriteError(message);
                throw new Exception(message + Environment.NewLine +
                                    $"See {Constants.HelpUrls.GcmCredentialStores} for more information."
                );
            }

            if (!_context.SessionManager.IsDesktopSession)
            {
                var message = $"Cannot use the '{StoreNames.SecretService}' credential backing store without a graphical interface present.";
                _context.Trace2.WriteError(message);
                throw new Exception(message + Environment.NewLine +
                                    $"See {Constants.HelpUrls.GcmCredentialStores} for more information."
                );
            }
        }

        private void ValidateGpgPass(out string storeRoot, out string execPath)
        {
            if (!PlatformUtils.IsPosix())
            {
                var message = $"Can only use the '{StoreNames.Gpg}' credential store on POSIX systems.";
                _context.Trace2.WriteError(message);
                throw new Exception(message + Environment.NewLine +
                                    $"See {Constants.HelpUrls.GcmCredentialStores} for more information."
                );
            }

            execPath = GetGpgPath();

View on GitHub (pinned to e8ce762cd0)