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

Can only use the ' ' credential store on macOS. See for…

Error message

Can only use the '{StoreNames.MacOSKeychain}' credential store on macOS.
See {Constants.HelpUrls.GcmCredentialStores} for more information.

What it means

GCM's CredentialStore.ValidateMacOSKeychain throws this generic Exception when the credential store type is explicitly configured to '{macOSKeychain}' but the host is not macOS. The macOS Keychain backing store only exists on macOS, so selecting it elsewhere is a configuration error caught before any credential operation runs.

Solutions

  1. Remove the credential.store / GCM_CREDENTIAL_STORE setting so GCM auto-selects the platform default store.
  2. Set credential.store to the correct store for the OS (e.g. 'wincredman' on Windows, 'secretservice' or 'gpg'/'cache' on Linux).
  3. If config must be shared, scope the macOS-specific store setting to a per-machine include (includeIf) rather than globally.

Example fix

// before (Linux ~/.gitconfig)
[credential]
	store = macOSkeychain
// after
[credential]
	# let GCM pick the platform default
	# store = secretservice
Defensive patterns

Strategy: validation

Validate before calling

const isMac = process.platform === 'darwin';
if (storeType === 'macOSKeychain' && !isMac) {
  throw new Error('macOSKeychain credential store requires macOS');
}

Type guard

const isValidStoreForPlatform = (store: string) =>
  store !== 'macOSKeychain' || process.platform === 'darwin';

Prevention

When it happens

Trigger: Setting credential.store (or GCM_CREDENTIAL_STORE) to StoreNames.MacOSKeychain on Windows or Linux; EnsureBackingStore dispatches to ValidateMacOSKeychain which fails the PlatformUtils.IsMacOS() check.

Common situations: Copying a .gitconfig or GCM env config from a Mac to a Linux CI box or Windows machine; documentation snippets assuming macOS; team-shared config files that pin the store type.

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

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

Appendix: source

Thrown at src/Core/CredentialStore.cs:247

            // Check for a redirected credential store location
            if (!_context.Settings.TryGetSetting(
                Constants.EnvironmentVariables.GcmDpapiStorePath,
                Constants.GitConfiguration.Credential.SectionName,
                Constants.GitConfiguration.Credential.DpapiStorePath,
                out storeRoot))
            {
                // Use default store root at ~/.gcm/dpapi_store
                storeRoot = Path.Combine(_context.FileSystem.UserDataDirectoryPath, "dpapi_store");
            }
        }

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

        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)
            {

View on GitHub (pinned to e8ce762cd0)