{"record":{"id":"783f7e11e4190783","repo":"microsoft/semantic-kernel","slug":"failed-to-create-a-session-please-check-your-conf","errorCode":null,"errorMessage":"Failed to create a session. Please check your configuration.","messagePattern":"Failed to create a session\\. Please check your configuration\\.","errorType":"exception","errorClass":"KernelPluginInvalidConfigurationError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/mcp.py","lineNumber":345,"sourceCode":"                await self._exit_stack.aclose()\n                ready_event.set()\n                raise KernelPluginInvalidConfigurationError(\n                    \"Failed to connect to the MCP server. Please check your configuration.\"\n                ) from ex\n            try:\n                session = await self._exit_stack.enter_async_context(\n                    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()","sourceCodeStart":327,"sourceCodeEnd":363,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/mcp.py#L327-L363","documentation":"Thrown by MCPPluginBase._inner_connect (mcp.py:345) as a KernelPluginInvalidConfigurationError when ClientSession(...) construction fails after the transport was obtained. This is distinct from transport creation (1350) and from the initialize handshake (1352): the session object itself could not be created from the read/write streams.","triggerScenarios":"ClientSession instantiation raises, e.g. incompatible transport stream shapes, a programming error in callbacks (message_handler/logging_callback/sampling_callback signatures), or an internal mcp ClientSession failure at mcp.py:333-347.","commonSituations":"Passing custom callbacks with wrong signatures; mcp library version mismatch where ClientSession expects different streams; a subclass overriding get_mcp_client returning malformed transport tuples; corrupted state after a prior failed connect.","solutions":["Inspect the chained __cause__ for the exact ClientSession error.","Pin compatible versions of the mcp and semantic-kernel packages.","If supplying custom message_handler/logging_callback/sampling_callback, match the expected callable signatures exactly.","Reproduce with a minimal plugin config to isolate whether a callback or the transport is at fault."],"exampleFix":"# before (callback with wrong signature)\nplugin = MCPStdioPlugin(..., logging_callback=lambda level, data: None)\n\n# after (match the expected (level, data, logger) shape per mcp ClientSession)\nplugin = MCPStdioPlugin(..., logging_callback=lambda level, data, logger=None: logger.info(data))","handlingStrategy":"try-catch","validationCode":"# validate callback signatures match mcp ClientSession expectations before passing\nimport inspect\n\ndef callbacks_well_formed(message_handler, logging_callback, sampling_callback) -> bool:\n    for cb in (message_handler, logging_callback, sampling_callback):\n        if cb is not None and not callable(cb):\n            return False\n    return True","typeGuard":"def is_callable_or_none(cb) -> bool:\n    return cb is None or callable(cb)","tryCatchPattern":"from semantic_kernel.exceptions.kernel_exceptions import KernelPluginInvalidConfigurationError\n\ntry:\n    async with plugin:\n        ...\nexcept KernelPluginInvalidConfigurationError as ex:\n    if \"Failed to create a session\" in str(ex):\n        log.error(\"session creation failed: %r\", ex.__cause__)\n        # simplify callbacks and retry, or pin compatible mcp version","preventionTips":["Match message_handler/logging_callback/sampling_callback signatures to the mcp ClientSession contract.","Pin compatible versions of mcp and semantic-kernel.","Reproduce with default callbacks to isolate whether a custom callback is the cause.","Inspect __cause__ for the exact ClientSession error."],"tags":["mcp","connection","session","configuration","callbacks"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}