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

No protocol name mapping is defined for the given…

Error message

No protocol name mapping is defined for the given capability.

What it means

The default arm of GitCapabilities.ToProtocolName's switch throws ArgumentOutOfRangeException when given a capability value that has no defined protocol name mapping. Unlike None (a deliberate ArgumentException), this fires for any unrecognized or unimplemented enum value — typically a newly added GitCapabilities member that lacks a mapping entry.

Solutions

1. Update to matching library versions on all sides so both the enum and the mapping table agree.
2. Add a mapping case for the new capability in ToProtocolName if you own the code.
3. Validate capability values before casting; never cast untrusted integers to the enum without Enum.IsDefined.

Example fix

// before
var cap = (GitCapabilities.State)rawValue; // unmapped value
var name = cap.ToProtocolName(); // ArgumentOutOfRangeException
// after
if (Enum.IsDefined(typeof(GitCapabilities.State), rawValue))
    var name = ((GitCapabilities.State)rawValue).ToProtocolName();

if (!Enum.IsDefined(typeof(GitCapabilities.State), rawValue))
    throw new InvalidOperationException($"Unknown capability value {rawValue}");

bool IsKnownCapability(GitCapabilities.State c) =>
    c == GitCapabilities.None || c == GitCapabilities.State; // extend as mappings are added

try
{
    var name = capability.ToProtocolName();
}
catch (ArgumentOutOfRangeException ex)
{
    logger.LogWarning(ex, $"Capability {capability} has no protocol mapping; check library version alignment.");
}

When it happens

Trigger: Calling ToProtocolName (directly or via ToProtocolNames) with an enum value not covered by the switch — e.g. a capability added in a newer version of the library while the mapping table was not updated, or a cast of an arbitrary integer to GitCapabilities.State.

Common situations: Version mismatch between components sharing the GitCapabilities enum; custom code casting raw protocol strings/ints into the enum; library upgrade where new capabilities were introduced.

Related errors

• Unknown authentication mode
• Unexpected AuthenticationModes returned from prompt
• Unsupported workload federation scenario.
• Unexpected interaction mode.
• Cannot render the None capability to a protocol name.

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

Appendix: source

Thrown at src/Core/GitCapabilities.cs:96

    /// <remarks>
    /// The protocol name is always lowercase. New entries must be added here
    /// in lockstep with new <see cref="GitCapabilities"/> flag values to avoid
    /// emitting an incorrect name to Git.
    /// </remarks>
    public static string ToProtocolName(GitCapabilities capability)
    {
        // Add each flag's protocol name here as the capability is wired up.
        // The default lowercase enum name is intentionally NOT used because
        // some protocol names will not be a single token (e.g. authtype is fine
        // but a hypothetical "PasswordExpiryUtc" would have to map to a
        // protocol name distinct from its .NET enum name).
        return capability switch
        {
            GitCapabilities.State => "state",
            GitCapabilities.None => throw new ArgumentException(
                "Cannot render the None capability to a protocol name.",
                nameof(capability)),
            _ => throw new ArgumentOutOfRangeException(
                nameof(capability),
                capability,
                "No protocol name mapping is defined for the given capability."),
        };
    }

    /// <summary>
    /// Enumerate each individual <see cref="GitCapabilities"/> flag set in
    /// <paramref name="capabilities"/>, rendered to its on-the-wire protocol name.
    /// </summary>
    /// <remarks>
    /// Returns an empty sequence for <see cref="GitCapabilities.None"/>. Each
    /// emitted name comes from <see cref="ToProtocolName"/>.
    /// </remarks>
    public static IEnumerable<string> ToProtocolNames(GitCapabilities capabilities)
    {
        if (capabilities == GitCapabilities.None)
        {

View on GitHub (pinned to e8ce762cd0)