microsoft/semantic-kernel · critical · AgentInitializationException

Authentication failed; see logs for category and correlation

Error message

Authentication failed; see logs for category and correlation code.

What it means

Raised by _CopilotStudioAgentTokenFactory._unwrap when the MSAL token-acquisition result dict does not contain an 'access_token' key. MSAL returns error/correlation_id fields instead, which are logged via _log_auth_failure before the exception is thrown. It is an AgentInitializationException (subclass of AgentException -> KernelException), surfaced during CopilotStudioAgent.create_client() / __init__ when no pre-built client is supplied.

Source

Thrown at python/semantic_kernel/agents/copilot_studio/copilot_studio_agent.py:175

        app = PublicClientApplication(
            self.settings.app_client_id,
            authority=f"https://login.microsoftonline.com/{self.settings.tenant_id}",
            token_cache=self.cache,
        )
        accounts = app.get_accounts()
        result = (
            app.acquire_token_silent(self.scopes, account=accounts[0])
            if accounts
            else app.acquire_token_interactive(self.scopes)
        )
        return self._unwrap(result)

    @staticmethod
    def _unwrap(result: dict[str, Any]) -> str:
        if "access_token" in result:
            return result["access_token"]
        _log_auth_failure(result)
        raise AgentInitializationException("Authentication failed; see logs for category and correlation code.")

    @staticmethod
    def _cert_thumbprint(cert_path: Path) -> str:
        import hashlib
        import ssl

        pem_bytes = Path(cert_path).read_bytes()
        der_bytes = ssl.PEM_cert_to_DER_cert(pem_bytes.decode())
        # SHA-1 is not used here as a security primitive; it is required to compute the X.509 certificate thumbprint
        # (the `x5t` JWT header value), which MSAL and Microsoft Entra ID mandate to be a SHA-1 digest for the
        # `thumbprint` client credential. Hence the `usedforsecurity=False` flag.
        return hashlib.sha1(der_bytes, usedforsecurity=False).hexdigest().upper()  # CodeQL [SM02167] x5t thumbprint


# endregion


# region CopilotStudioAgentThread

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Check the logs for the logged error category and correlation_id (first 8 chars) to identify the exact MSAL error (e.g. invalid_client, invalid_grant).
2. Verify app_client_id and tenant_id are correct and that the Entra app registration has the required delegated/application permissions for the Power Platform API.
3. If using interactive mode in a headless/CI environment, switch to a mode that does not require a browser, or run once on a workstation to populate the token cache.
4. Rotate or correct the client_secret / client_certificate if the error is invalid_client.
5. Delete the token cache file (TOKEN_CACHE_PATH_INTERACTIVE or the default bin/token_cache_interactive.bin) if it is corrupted and re-authenticate.

Example fix

# before — headless server with interactive auth fails
agent = CopilotStudioAgent()  # triggers interactive browser prompt that cannot complete

# after — provide correct credentials and use a pre-authenticated client
client = CopilotStudioAgent.create_client(
    auth_mode="interactive",
    app_client_id=os.environ["APP_CLIENT_ID"],
    tenant_id=os.environ["TENANT_ID"],
)
agent = CopilotStudioAgent(client=client)

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException

try:
    agent = CopilotStudioAgent()
except AgentInitializationException as exc:
    # Check logs for the MSAL error category + correlation_id
    logger.error("Copilot Studio auth failed: %s", exc)
    raise

When it happens

Trigger: Calling CopilotStudioAgent() or CopilotStudioAgent.create_client() without a client argument triggers token acquisition. The acquire() path calls _acquire_interactive_token() or _acquire_service_token(), whose MSAL call (acquire_token_silent / acquire_token_interactive / acquire_token_for_client) returns a dict lacking 'access_token' — e.g. invalid_client, invalid_grant, consent_required, or expired secret.

Common situations: Wrong or expired app_client_id / tenant_id / client_secret in the .env file; the Entra app registration lacks API permissions for https://api.powerplatform.com/.default; interactive browser prompt cancelled or blocked in a headless environment; token cache corrupted; SERVICE mode used (which is explicitly unsupported and always errors).

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Copilot Studio SERVICE authentication is not available yet.
• Please provide either an api_key, ad_token, ad_token_provide
• No token received from token generation.
• Failed to generate token using bot_secret.
• No token received.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/a7472b664137e18d. Report an issue: GitHub.