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

Unknown mode value in response

Error message

Unknown mode value in response '{responseMode}'

What it means

Thrown in GetAuthenticationViaHelperAsync when the 'mode' value returned by the GitLab helper is not one of the recognized values (pat, browser, basic; compared case-insensitively). This is a strict protocol enum check on the helper's response.

Solutions

  1. Change the helper to emit exactly one of: pat, browser, or basic (lowercase, no whitespace).
  2. Trim whitespace/CR characters from helper output before printing the mode line.
  3. Check GCM version documentation for supported mode values if the helper was written against a different release.

Example fix

// before
echo "mode=token"
// after
echo "mode=pat"
Defensive patterns

Strategy: validation

Validate before calling

case "$MODE" in
  pat|browser|basic) echo "mode=$MODE" ;;
  *) echo "Invalid mode: $MODE" >&2; exit 1 ;;
esac

Try / catch

try {
  var result = await auth.GetAuthenticationAsync(...);
} catch (Trace2Exception ex) when (ex.Message.StartsWith("Unknown mode value in response")) {
  // log the raw mode value and fall back to built-in GitLab auth
}

Prevention

When it happens

Trigger: Helper returns mode=token, mode=oauth, mode=PAT with trailing whitespace/newline artifacts, or any unexpected string; mode switch with unrecognized default branch hit.

Common situations: Hand-rolled helper scripts using a plausible-but-unsupported mode name; helpers written for GitHub's protocol reused for GitLab; shell scripts emitting CRLF line endings that corrupt the parsed value.

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/aa7133a40125df2f. Report an issue: GitHub.

Appendix: source

Thrown at src/GitLab/GitLabAuthentication.cs:256

                case "browser":
                    return new AuthenticationPromptResult(AuthenticationModes.Browser);

                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<OAuth2TokenResult> GetOAuthTokenViaBrowserAsync(Uri targetUri, IEnumerable<string> scopes)
        {
            ThrowIfUserInteractionDisabled();

            var oauthClient = new GitLabOAuth2Client(HttpClient, Context.Settings, targetUri, Context.Trace2);

            // 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 { };

View on GitHub (pinned to e8ce762cd0)