{"record":{"id":"681385a018518bf6","repo":"PrefectHQ/fastmcp","slug":"failed-to-initialize-server-session","errorCode":null,"errorMessage":"Failed to initialize server session","messagePattern":"Failed to initialize server session","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/client/client.py","lineNumber":889,"sourceCode":"            with anyio.fail_after(timeout):\n                if effective_mode == \"legacy\":\n                    self._session_state.initialize_result = (\n                        await self.session.initialize()\n                    )\n                elif effective_mode == \"auto\":\n                    async with _conformant_discover_only(self.session):\n                        await negotiate_auto(self.session)\n                    # auto may have fallen back to the legacy handshake; surface its\n                    # InitializeResult through the existing public property when so.\n                    self._session_state.initialize_result = (\n                        self.session.initialize_result\n                    )\n                else:\n                    self.session.adopt(\n                        self._prior_discover or _synthesize_discover(self.mode)\n                    )\n        except TimeoutError as e:\n            raise RuntimeError(\"Failed to initialize server session\") from e\n\n    async def initialize(\n        self,\n        timeout: datetime.timedelta | float | int | None = None,\n    ) -> mcp_types.InitializeResult:\n        \"\"\"Send an initialize request to the server.\n\n        This method performs the MCP initialization handshake with the server,\n        exchanging capabilities and server information. It is idempotent - calling\n        it multiple times returns the cached result from the first call.\n\n        The initialization happens automatically when entering the client context\n        manager unless `auto_initialize=False` was set during client construction.\n        Manual calls to this method are only needed when auto-initialization is disabled.\n\n        With `mode=\"auto\"` or a pinned modern version, connect-time negotiation may adopt\n        the modern `server/discover` era, which has no `InitializeResult`; in that case\n        this method raises. Read `protocol_version`, `server_info`,","sourceCodeStart":871,"sourceCodeEnd":907,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/client/client.py#L871-L907","documentation":"During the MCP initialize handshake the client waits for the server's response within a timeout. If negotiation times out, FastMCP raises this RuntimeError with the TimeoutError chained as cause. It means the server did not complete initialization in time.","triggerScenarios":"`client._negotiate()` (via auto_initialize on connect or `await client.initialize()`) exceeds the timeout because the server is slow to start, hung, or unreachable.","commonSituations":"Cold-starting a stdio server (heavy imports, slow container) exceeding the default timeout; remote server behind a slow proxy; wrong URL/port causing a silent hang; server blocking during auth.","solutions":["Increase the timeout: `await client.initialize(timeout=30)`","Verify the server actually starts and responds (run it manually, check output)","Check network path and auth for remote transports","Retry once with a longer timeout before giving up"],"exampleFix":"// before\nasync with client:\n    result = await client.initialize()  # default timeout\n\n// after\nasync with client:\n    result = await client.initialize(timeout=30.0)","handlingStrategy":"retry","validationCode":"# Health-check the server before the handshake (HTTP example)\n# probe the endpoint with a short request first; for stdio, launch and\n# confirm the process is still alive before connecting","typeGuard":null,"tryCatchPattern":"try:\n    result = await client.initialize(timeout=10)\nexcept RuntimeError as e:\n    if \"Failed to initialize\" in str(e):\n        result = await client.initialize(timeout=60)\n    else:\n        raise","preventionTips":["Pass an explicit generous timeout for slow-starting servers","Warm up / health-check the server before connecting","Confirm network reachability and auth for remote transports"],"tags":["python","timeout","handshake","initialization"],"backgroundTag":"initialize-timeout","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}