microsoft/semantic-kernel · error · KernelPluginInvalidConfigurationError

Failed to initialize session. Please check your…

Error message

Failed to initialize session. Please check your configuration.

What it means

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.

Solutions

  1. Ensure the MCP server and the mcp client library speak the same protocol version (upgrade/downgrade one side).
  2. Increase request_timeout if the server is slow to initialize.
  3. Run the server with verbose logging and confirm it completes its own initialize handshake with a known-good client (e.g. the mcp inspector).
  4. Inspect the chained __cause__ for the protocol or timeout error.

Example fix

# before
plugin = MCPStdioPlugin(name="x", command="...", request_timeout=1)

# after
plugin = MCPStdioPlugin(name="x", command="...", request_timeout=30)
Defensive patterns

Strategy: try-catch

Validate before calling

# smoke-test the server with a known-good MCP client (e.g. mcp inspector) before wiring SK
# and size request_timeout to the server's init latency
recommended_timeout = max(30, estimated_server_startup_seconds * 2)

Type guard

def timeout_is_reasonable(request_timeout: int | None) -> bool:
    return request_timeout is None or request_timeout >= 10

Try / catch

from semantic_kernel.exceptions.kernel_exceptions import KernelPluginInvalidConfigurationError

try:
    async with MCPStdioPlugin(..., request_timeout=30) as plugin:
        ...
except KernelPluginInvalidConfigurationError as ex:
    if "Failed to initialize session" in str(ex):
        log.error("handshake failed: %r", ex.__cause__)
        # align client/server protocol versions, raise timeout, or check server logs

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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

Appendix: source

Thrown at python/semantic_kernel/connectors/mcp.py:352

                    ClientSession(
                        read_stream=transport[0],
                        write_stream=transport[1],
                        read_timeout_seconds=timedelta(seconds=self.request_timeout) if self.request_timeout else None,
                        message_handler=self.message_handler,
                        logging_callback=self.logging_callback,
                        sampling_callback=self.sampling_callback,
                    )
                )
            except Exception as ex:
                await self._exit_stack.aclose()
                raise KernelPluginInvalidConfigurationError(
                    "Failed to create a session. Please check your configuration."
                ) from ex
            try:
                await session.initialize()
            except Exception as ex:
                await self._exit_stack.aclose()
                raise KernelPluginInvalidConfigurationError(
                    "Failed to initialize session. Please check your configuration."
                ) from ex
            self.session = session
        elif self.session._request_id == 0:
            # If the session is not initialized, we need to reinitialize it
            await self.session.initialize()
        logger.debug("Connected to MCP server: %s", self.session)
        if self.load_tools_flag:
            await self.load_tools()
        if self.load_prompts_flag:
            await self.load_prompts()

        if logger.level != logging.NOTSET:
            try:
                await self.session.set_logging_level(
                    next(level for level, value in LOG_LEVEL_MAPPING.items() if value == logger.level)
                )
            except Exception:

View on GitHub (pinned to c028a0c7dc)