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

Unknown mode value in response

Error message

Unknown mode value in response '{responseMode}'

What it means

After reading the 'mode' value from the helper response, GetAuthenticationModeViaHelperAsync switches on it and only recognizes 'browser' and 'devicecode'. Any other string raises a Trace2Exception naming the unknown value.

Solutions

  1. Align helper and library versions so the set of supported modes matches
  2. Fix the helper output to emit exactly 'browser' or 'devicecode'
  3. Update GCM to a version that recognizes the new mode value
  4. Inspect the reported responseMode value in the message to identify the offending source
Defensive patterns

Strategy: try-catch

Validate before calling

var known = new[] { "browser", "devicecode" }; if (responseMode != null && !known.Contains(responseMode.ToLowerInvariant())) throw new InvalidOperationException($"Unknown mode '{responseMode}' from helper.");

Try / catch

try { mode = await oauth.GetAuthenticationModeAsync(...); } catch (Exception ex) when (ex.Message.StartsWith("Unknown mode value")) { mode = OAuthAuthenticationModes.Browser; }

Prevention

When it happens

Trigger: The helper returns a 'mode' string other than browser/devicecode — e.g. a typo, a new mode added in a newer helper that this library doesn't know, or localized/case-mangled output (though matching is case-insensitive).

Common situations: Running a newer helper that supports an authentication mode the linked library predates; custom or shimmed helper scripts emitting non-standard mode values.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at src/Core/Authentication/OAuthAuthentication.cs:172

            }

            IDictionary<string, string> resultDict = await InvokeHelperAsync(command, promptArgs.ToString());

            if (!resultDict.TryGetValue("mode", out string responseMode))
            {
                throw new Trace2Exception(Context.Trace2, "Missing 'mode' in response");
            }

            switch (responseMode.ToLowerInvariant())
            {
                case "browser":
                    return OAuthAuthenticationModes.Browser;

                case "devicecode":
                    return OAuthAuthenticationModes.DeviceCode;

                default:
                    throw new Trace2Exception(Context.Trace2,
                        $"Unknown mode value in response '{responseMode}'");
            }
        }

        public async Task<OAuth2TokenResult> GetTokenByBrowserAsync(OAuth2Client client, string[] scopes)
        {
            ThrowIfUserInteractionDisabled();

            // We require a desktop session to launch the user's default web browser
            if (!Context.SessionManager.IsDesktopSession)
            {
                throw new Trace2InvalidOperationException(Context.Trace2,
                    "Browser authentication requires a desktop session");
            }

            var browserOptions = new OAuth2WebBrowserOptions();
            var browser = new OAuth2SystemWebBrowser(Context.SessionManager, browserOptions);
            var authCode = await client.GetAuthorizationCodeAsync(scopes, browser, CancellationToken.None);

View on GitHub (pinned to e8ce762cd0)