github/copilot-sdk · warning · InvalidOperationException

Unknown GitHub token request reason

Error message

Unknown GitHub token request reason '{request.Reason}'.

What it means

Thrown as InvalidOperationException when the CLI's GitHub token acquire request carries a Reason value that the client cannot map to a known GitHubTokenRequestReason (only Initial and Refresh are recognized). This protects against forward/backward version drift where the CLI introduces a new acquire reason the library doesn't understand.

Solutions

1. Upgrade the dotnet client library to a version matching (or newer than) the CLI so the new reason is supported
2. Pin the Copilot CLI version to one compatible with your client library version
3. Log the raw request.Reason value from the exception message and check release notes for the new enum member
4. Wrap provider dispatch in try-catch and report/handle unknown reasons gracefully if you must tolerate version drift

Example fix

// before
// older SDK: throws on new CLI reason values
// after
dotnet add package GitHub.Copilot.SDK --version <latest>  # support new GitHubTokenAcquireReason values
# and/or pin CLI:
copilot --version  # pin to version matching the SDK

// preflight version compatibility
var cliVersion = await GetCliVersionAsync();
if (!IsCompatibleWithSdk(cliVersion)) throw new InvalidOperationException("Upgrade SDK or pin CLI version");

try { await sessionOp(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Unknown GitHub token request reason"))
{ logger.LogWarning(ex, "CLI sent unsupported token reason; upgrade SDK"); /* fail over or re-auth */ }

When it happens

Trigger: The CLI sends a GitHubTokenAcquireRequest whose request.Reason enum value is neither Initial nor Refresh — typically a newer CLI introducing a new reason (e.g. renewal/rotation) used with an older client library.

Common situations: Copilot CLI auto-updated to a version newer than the .NET SDK; mismatched pinned versions in CI; a custom/proxying layer injecting an unexpected reason 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

• Unknown GitHub token provider registration ID
• Unknown AgentMode value: + value
• Unknown AskUserVariant value: + value
• Unknown AutoTier value: + value
• Unknown MessageSource value: + value

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/824cb5ebc76fd8e5. Report an issue: GitHub.

Appendix: source

Thrown at dotnet/src/Client.cs:2105

    private void ClearGitHubTokenProviders() => _gitHubTokenProviders.Clear();

    private sealed class GitHubTokenAdapter(CopilotClient client) : IGitHubTokenHandler
    {
        public async Task<GitHubTokenAcquireResult> GetTokenAsync(
            GitHubTokenAcquireRequest request,
            CancellationToken cancellationToken = default)
        {
            if (!client._gitHubTokenProviders.TryGetValue(request.RegistrationId, out var provider))
            {
                throw new InvalidOperationException(
                    $"Unknown GitHub token provider registration ID '{request.RegistrationId}'.");
            }

            var reason = request.Reason == GitHubTokenAcquireReason.Initial
                ? GitHubTokenRequestReason.Initial
                : request.Reason == GitHubTokenAcquireReason.Refresh
                    ? GitHubTokenRequestReason.Refresh
                    : throw new InvalidOperationException($"Unknown GitHub token request reason '{request.Reason}'.");
            var result = await provider(new GitHubTokenProviderArgs
            {
                Host = request.Host,
                SessionId = request.SessionId,
                Reason = reason,
            }).ConfigureAwait(false);

            if (result is { Cancelled: true })
            {
                return new GitHubTokenAcquireResultCancelled();
            }
            if (result?.Token is not { } token)
            {
                throw new InvalidOperationException(
                    "GitHub token provider returned neither a token nor cancellation.");
            }
            return new GitHubTokenAcquireResultToken
            {

View on GitHub (pinned to cd8cf15dc3)