{"record":{"id":"a7472b664137e18d","repo":"microsoft/semantic-kernel","slug":"authentication-failed-see-logs-for-category-and-c","errorCode":null,"errorMessage":"Authentication failed; see logs for category and correlation code.","messagePattern":"Authentication failed; see logs for category and correlation code\\.","errorType":"exception","errorClass":"AgentInitializationException","httpStatus":null,"severity":"critical","filePath":"python/semantic_kernel/agents/copilot_studio/copilot_studio_agent.py","lineNumber":175,"sourceCode":"        app = PublicClientApplication(\n            self.settings.app_client_id,\n            authority=f\"https://login.microsoftonline.com/{self.settings.tenant_id}\",\n            token_cache=self.cache,\n        )\n        accounts = app.get_accounts()\n        result = (\n            app.acquire_token_silent(self.scopes, account=accounts[0])\n            if accounts\n            else app.acquire_token_interactive(self.scopes)\n        )\n        return self._unwrap(result)\n\n    @staticmethod\n    def _unwrap(result: dict[str, Any]) -> str:\n        if \"access_token\" in result:\n            return result[\"access_token\"]\n        _log_auth_failure(result)\n        raise AgentInitializationException(\"Authentication failed; see logs for category and correlation code.\")\n\n    @staticmethod\n    def _cert_thumbprint(cert_path: Path) -> str:\n        import hashlib\n        import ssl\n\n        pem_bytes = Path(cert_path).read_bytes()\n        der_bytes = ssl.PEM_cert_to_DER_cert(pem_bytes.decode())\n        # SHA-1 is not used here as a security primitive; it is required to compute the X.509 certificate thumbprint\n        # (the `x5t` JWT header value), which MSAL and Microsoft Entra ID mandate to be a SHA-1 digest for the\n        # `thumbprint` client credential. Hence the `usedforsecurity=False` flag.\n        return hashlib.sha1(der_bytes, usedforsecurity=False).hexdigest().upper()  # CodeQL [SM02167] x5t thumbprint\n\n\n# endregion\n\n\n# region CopilotStudioAgentThread","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/copilot_studio/copilot_studio_agent.py#L157-L193","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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."],"exampleFix":"# before — headless server with interactive auth fails\nagent = CopilotStudioAgent()  # triggers interactive browser prompt that cannot complete\n\n# after — provide correct credentials and use a pre-authenticated client\nclient = CopilotStudioAgent.create_client(\n    auth_mode=\"interactive\",\n    app_client_id=os.environ[\"APP_CLIENT_ID\"],\n    tenant_id=os.environ[\"TENANT_ID\"],\n)\nagent = CopilotStudioAgent(client=client)","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException\n\ntry:\n    agent = CopilotStudioAgent()\nexcept AgentInitializationException as exc:\n    # Check logs for the MSAL error category + correlation_id\n    logger.error(\"Copilot Studio auth failed: %s\", exc)\n    raise","preventionTips":["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."],"tags":["authentication","msal","copilot-studio","entra-id","initialization"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}