{"record":{"id":"43f2910ad34cd7f2","repo":"microsoft/semantic-kernel","slug":"failed-to-initialize-session-please-check-your-co","errorCode":null,"errorMessage":"Failed to initialize session. Please check your configuration.","messagePattern":"Failed to initialize session\\. Please check your configuration\\.","errorType":"exception","errorClass":"KernelPluginInvalidConfigurationError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/mcp.py","lineNumber":352,"sourceCode":"                    ClientSession(\n                        read_stream=transport[0],\n                        write_stream=transport[1],\n                        read_timeout_seconds=timedelta(seconds=self.request_timeout) if self.request_timeout else None,\n                        message_handler=self.message_handler,\n                        logging_callback=self.logging_callback,\n                        sampling_callback=self.sampling_callback,\n                    )\n                )\n            except Exception as ex:\n                await self._exit_stack.aclose()\n                raise KernelPluginInvalidConfigurationError(\n                    \"Failed to create a session. Please check your configuration.\"\n                ) from ex\n            try:\n                await session.initialize()\n            except Exception as ex:\n                await self._exit_stack.aclose()\n                raise KernelPluginInvalidConfigurationError(\n                    \"Failed to initialize session. Please check your configuration.\"\n                ) from ex\n            self.session = session\n        elif self.session._request_id == 0:\n            # If the session is not initialized, we need to reinitialize it\n            await self.session.initialize()\n        logger.debug(\"Connected to MCP server: %s\", self.session)\n        if self.load_tools_flag:\n            await self.load_tools()\n        if self.load_prompts_flag:\n            await self.load_prompts()\n\n        if logger.level != logging.NOTSET:\n            try:\n                await self.session.set_logging_level(\n                    next(level for level, value in LOG_LEVEL_MAPPING.items() if value == logger.level)\n                )\n            except Exception:","sourceCodeStart":334,"sourceCodeEnd":370,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/mcp.py#L334-L370","documentation":"Thrown by MCPPluginBase._inner_connect (mcp.py:352) as a KernelPluginInvalidConfigurationError when session.initialize() fails. initialize() performs the MCP capability handshake (protocol version negotiation, capabilities exchange). A failure here means the server answered the transport but the handshake did not complete successfully.","triggerScenarios":"Server and client use incompatible MCP protocol versions; the server crashed or returned an error during initialize; the server timed out mid-handshake; request_timeout too small for a slow server. Originates at mcp.py:348-354.","commonSituations":"MCP server built against an older/newer protocol version than the client library; server requires auth not provided; slow-to-start servers hitting the default timeout; server throwing during capability advertisement; proxy stripping headers.","solutions":["Ensure the MCP server and the mcp client library speak the same protocol version (upgrade/downgrade one side).","Increase request_timeout if the server is slow to initialize.","Run the server with verbose logging and confirm it completes its own initialize handshake with a known-good client (e.g. the mcp inspector).","Inspect the chained __cause__ for the protocol or timeout error."],"exampleFix":"# before\nplugin = MCPStdioPlugin(name=\"x\", command=\"...\", request_timeout=1)\n\n# after\nplugin = MCPStdioPlugin(name=\"x\", command=\"...\", request_timeout=30)","handlingStrategy":"try-catch","validationCode":"# smoke-test the server with a known-good MCP client (e.g. mcp inspector) before wiring SK\n# and size request_timeout to the server's init latency\nrecommended_timeout = max(30, estimated_server_startup_seconds * 2)","typeGuard":"def timeout_is_reasonable(request_timeout: int | None) -> bool:\n    return request_timeout is None or request_timeout >= 10","tryCatchPattern":"from semantic_kernel.exceptions.kernel_exceptions import KernelPluginInvalidConfigurationError\n\ntry:\n    async with MCPStdioPlugin(..., request_timeout=30) as plugin:\n        ...\nexcept KernelPluginInvalidConfigurationError as ex:\n    if \"Failed to initialize session\" in str(ex):\n        log.error(\"handshake failed: %r\", ex.__cause__)\n        # align client/server protocol versions, raise timeout, or check server logs","preventionTips":["Keep the MCP server and client library on compatible protocol versions.","Set request_timeout generously for slow-starting servers.","Confirm the server completes initialize with the mcp inspector first.","Inspect __cause__ for protocol/timeout specifics."],"tags":["mcp","connection","handshake","protocol-version","configuration"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}