Skip to content

Improve auth error UX for CredentialUnavailableException in authenticated commands#3056

Draft
vcolin7 with Copilot wants to merge 2 commits into
mainfrom
copilot/fix-auth-credential-errors
Draft

Improve auth error UX for CredentialUnavailableException in authenticated commands#3056
vcolin7 with Copilot wants to merge 2 commits into
mainfrom
copilot/fix-auth-credential-errors

Conversation

Copilot AI commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

Telemetry showed 93% of cosmos_database_container_item_query failures were CredentialUnavailableException (HTTP 401) from expired/unconfigured Azure CLI credentials, surfaced as a verbose, non-actionable message. Since this exception derives from AuthenticationFailedException and error UX is centralized in the shared AuthenticatedCommand base, the fix applies to all authenticated tools, not just Cosmos.

Changes

  • AuthenticatedCommand.GetErrorMessage — Added a dedicated CredentialUnavailableException arm, matched before AuthenticationFailedException (its base type), returning an actionable message pointing users to az login. Status mapping is unchanged (still 401 via the base AuthenticationFailedException case).
  • Tests — Cover the new message, the 401 mapping, and the unchanged generic AuthenticationFailedException path.
  • CHANGELOG — Entry under 3.0.0-beta.27 (Unreleased).
protected override string GetErrorMessage(Exception ex) => ex switch
{
    // Derives from AuthenticationFailedException — must be matched first.
    CredentialUnavailableException credEx =>
        "Azure credentials not found or unavailable. Please run 'az login' to authenticate, then try again. " +
        $"For the complete list of supported credentials, see: https://aka.ms/azmcp/auth. Details: {credEx.Message}",
    AuthenticationFailedException authEx =>
        $"Authentication failed. Please run 'az login' to sign in to Azure. Details: {authEx.Message}",
    // ...unchanged
};

Notes

  • Timeout/cancellation paths (the ~5.6% "silent timeout" bucket) already map to detailed GatewayTimeout messages in this base class; deeper telemetry capture for swallowed timeouts is out of scope here.
  • A proactive pre-flight credential check was considered but not added — it would require threading a credential provider through every command path and add latency to all calls, disproportionate to the issue the message fix already resolves.
  • Local build/test could not run in the sandbox: the sole NuGet feed's package blob CDN (*.vsblob.vsassets.io) is DNS-blocked. CI will validate.

@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
Successfully started running 1 pipeline(s).
There may be pipelines that require an authorized user to comment /azp run to run.

Copilot AI changed the title [WIP] Fix auth credential errors in cosmos database query Improve auth error UX for CredentialUnavailableException in authenticated commands Jul 16, 2026
Copilot AI requested a review from vcolin7 July 16, 2026 00:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

cosmos_database_container_item_query: 93% of failures are auth credential errors (CredentialUnavailableException)

2 participants