{"record":{"id":"2f89138dd6e874ce","repo":"PrefectHQ/fastmcp","slug":"new-error-message-noriginal-error-e","errorCode":null,"errorMessage":"{new_error_message}\\nOriginal error: {e}","messagePattern":"(.+?)\\\\nOriginal error: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/server/http.py","lineNumber":110,"sourceCode":"            await self.session_manager.handle_request(scope, receive, send)\n        except RuntimeError as e:\n            if str(e) == \"Task group is not initialized. Make sure to use run().\":\n                logger.error(\n                    f\"Original RuntimeError from mcp library: {e}\", exc_info=True\n                )\n                new_error_message = (\n                    \"FastMCP's StreamableHTTPSessionManager task group was not initialized. \"\n                    \"This commonly occurs when the FastMCP application's lifespan is not \"\n                    \"passed to the parent ASGI application (e.g., FastAPI or Starlette). \"\n                    \"Please ensure you are setting `lifespan=mcp_app.lifespan` in your \"\n                    \"parent app's constructor, where `mcp_app` is the application instance \"\n                    \"returned by `fastmcp_instance.http_app()`. \\\\n\"\n                    \"For more details, see the FastMCP ASGI integration documentation: \"\n                    \"https://gofastmcp.com/deployment/asgi\"\n                )\n                # Raise a new RuntimeError that includes the original error's message\n                # for full context, but leads with the more helpful guidance.\n                raise RuntimeError(f\"{new_error_message}\\\\nOriginal error: {e}\") from e\n            else:\n                # Re-raise other RuntimeErrors if they don't match the specific message\n                raise\n\n\ndef _normalize_host(host: str) -> str:\n    host = host.strip().lower()\n    if not host:\n        return \"\"\n\n    if host.startswith(\"[\"):\n        end = host.find(\"]\")\n        if end == -1:\n            return host\n        return host[1:end]\n\n    if host.count(\":\") == 1:\n        return host.rsplit(\":\", 1)[0]","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/server/http.py#L92-L128","documentation":"When a RuntimeError other than the 'task group not initialized' sentinel escapes the ASGI wrapper, FastMCP inspects it and, if it matches its known-cause pattern, re-raises a new RuntimeError that leads with guidance (return the app via fastmcp_instance.http_app(), see the ASGI docs) and appends '\\nOriginal error: <e>' for full context.","triggerScenarios":"A RuntimeError raised during request handling in the StreamableHTTP session manager that matches FastMCP's known misconfiguration pattern — typically running the ASGI app incorrectly (e.g. the session manager not running due to missing lifespan).","commonSituations":"Mounting the streamable-http app without its lifespan; wrapping the ASGI callable manually instead of using http_app(); deployment misconfigurations where the session manager task group is not started.","solutions":["Serve the app returned by fastmcp_instance.http_app() rather than constructing/mounting internals yourself.","Follow the ASGI integration docs (https://gofastmcp.com/deployment/asgi) for correct mounting and lifespan wiring.","Ensure the session manager's run() executes via the app lifespan before serving requests.","Read the 'Original error' portion of the message to find the underlying cause and fix it."],"exampleFix":"// before\napp = FastMCP(\"x\")\nstarlette_app.mount(\"/mcp\", app._streamable_http_app_raw())\n// after\nhttp_app = app.http_app(path=\"/mcp\")\nstarlette_app.mount(\"/\", http_app)  # lifespan included","handlingStrategy":"try-catch","validationCode":"# verify the app came from http_app()\nassert hasattr(fastmcp_instance, \"http_app\")\nasgi = fastmcp_instance.http_app(path=\"/mcp\")","typeGuard":null,"tryCatchPattern":"try:\n    await asgi_app(scope, receive, send)\nexcept RuntimeError as e:\n    if \"fastmcp_instance.http_app\" in str(e):\n        logger.error(\"%s | underlying: %s\", e, e.__cause__)\n    raise","preventionTips":["Always serve the object returned by fastmcp_instance.http_app()","Follow the ASGI integration docs for custom mounts","Keep the lifespan that starts the session manager wired into the server"],"tags":["asgi","runtime-error","deployment"],"backgroundTag":"asgi-lifespan-misconfigured","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}