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' key, GetAuthenticationViaHelperAsync switches on its value against the known set: pat, browser, device, basic. Any other value means the helper and core disagree on the protocol vocabulary, so the method throws with the offending value interpolated into the message for diagnosis.

Solutions

  1. Align versions: upgrade Git Credential Manager core and helper together so the mode vocabulary matches
  2. Run the helper manually with GCM_TRACE enabled to see the exact mode value being emitted
  3. Fix custom helper/wrapper scripts to emit only supported modes: pat, browser, device, basic
  4. If a newer mode is genuinely needed, upgrade the core to a version whose switch statement recognizes it

Example fix

// before (custom helper)
output["mode"] = "web"; // unknown to core
// after
output["mode"] = "browser"; // supported: pat | browser | device | basic
Defensive patterns

Strategy: validation

Validate before calling

// Pre-validate the mode vocabulary your helper will emit
var allowedModes = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
    { "pat", "browser", "device", "basic" };
// custom helper side:
if (!allowedModes.Contains(chosenMode))
    chosenMode = "browser"; // coerce to a supported value

Type guard

static bool IsKnownAuthMode(string mode) =>
    mode is "pat" or "browser" or "device" or "basic";

Try / catch

try
{
    var result = await auth.GetAuthenticationAsync(uri, userName);
}
catch (Trace2Exception ex) when (ex.Message.StartsWith("Unknown mode value"))
{
    trace.WriteLine($"Helper/core version skew detected: {ex.Message}; upgrade GCM.");
    throw;
}

Prevention

When it happens

Trigger: Helper emits mode=<something unexpected> — e.g. a typo, a newer helper using an added mode the installed core doesn't know, or a corrupted/translated output value.

Common situations: Version skew: upgraded helper introduces a new mode string not understood by an older core; custom helper returning nonstandard mode values; manual edits or wrapper scripts altering helper output.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — 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/3d276bb33d37fc46. Report an issue: GitHub.

Appendix: source

Thrown at src/GitHub/GitHubAuthentication.cs:344

                case "device":
                    return new AuthenticationPromptResult(AuthenticationModes.Device);

                case "basic":
                    if (!resultDict.TryGetValue("username", out userName))
                    {
                        throw new Trace2Exception(Context.Trace2, "Missing 'username' in response");
                    }

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

                    return new AuthenticationPromptResult(
                        AuthenticationModes.Basic, new GitCredential(userName, password));

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

        public async Task<string> GetTwoFactorCodeAsync(Uri targetUri, bool isSms)
        {
            ThrowIfUserInteractionDisabled();

            if (Context.Settings.IsGuiPromptsEnabled && Context.SessionManager.IsDesktopSession)
            {
                if (TryFindHelperCommand(out string command, out string args))
                {
                    return await GetTwoFactorCodeViaHelperAsync(isSms, args, command);
                }

                return await GetTwoFactorCodeViaUiAsync(targetUri, isSms);
            }

View on GitHub (pinned to e8ce762cd0)