microsoft/semantic-kernel · critical · AgentInitializationException

Authentication failed; see logs for category and…

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.

Solutions

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).
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.
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.
Rotate or correct the client_secret / client_certificate if the error is invalid_client.
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)

Defensive patterns

Strategy: try-catch

Try / catch

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

Prevention

Pre-validate that app_client_id, tenant_id, and client_secret/certificate are set and non-empty before constructing the agent.
In headless environments, pre-populate the token cache on a workstation and copy it, or use certificate-based service auth once supported.
Monitor the 'semantic_kernel.agents.copilot_studio' logger at ERROR level to capture the category and correlation_id on failure.

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

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

Appendix: source

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

        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.")


# endregion


# region CopilotStudioAgentThread


@experimental
class CopilotStudioAgentThread(AgentThread):
    """The Copilot Studio Agent Thread."""

    def __init__(
        self,
        client: CopilotClient,
        conversation_id: str | None = None,
    ) -> None:
        """Initializes a new instance of the CopilotStudioAgentThread class.

View on GitHub (pinned to 6eab62d273)