integration tests and better error

.github/workflows/run-integration-tests.yml

@@ -0,0 +1,50 @@
+name: Run integration tests
+
+env:
+  # enable colored output
+  PY_COLORS: 1
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "integration_tests/**"
+      - "uv.lock"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+
+  # run on all pull requests because these checks are required and will block merges otherwise
+  pull_request:
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  run_tests:
+    name: "Run tests: Python ${{ matrix.python-version }} on ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10"]
+      fail-fast: false
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install FastMCP
+        run: uv sync --locked
+
+      - name: Run tests
+        run: uv run pytest integration_tests

integration_tests/test_repro_518_output.py

@@ -0,0 +1,89 @@
+import os
+import subprocess
+import sys
+import tempfile
+import time
+
+import httpx
+import pytest
+
+PYTHON_EXE = sys.executable
+
+SERVER_CODE = """
+import uvicorn
+from fastapi import FastAPI
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+@mcp.tool("dummy_tool", "A simple dummy tool for the test server")
+def add(a: int, b: int) -> int:
+    return a + b
+
+app = FastAPI() # Intentionally no lifespan=mcp.lifespan
+app.mount("/", mcp.http_app(transport="streamable-http"))
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8080, log_config=None)
+"""
+
+
+@pytest.mark.timeout(20)
+def test_server_shows_informative_error_on_stderr():
+    """
+    Runs a minimal FastMCP+FastAPI server (that omits lifespan wiring)
+    as a subprocess, triggers the error via an HTTP request, and then checks
+    if the server's stderr contains the specific informative error message for issue #518.
+    """
+    process = None
+    captured_stderr = ""
+
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".py", delete=False
+    ) as tmp_script:
+        tmp_script.write(SERVER_CODE)
+        tmp_script_path = tmp_script.name
+
+    try:
+        process = subprocess.Popen(
+            [PYTHON_EXE, "-u", tmp_script_path],
+            stderr=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            text=True,
+            universal_newlines=True,
+        )
+
+        time.sleep(3)
+
+        if process.poll() is None:
+            try:
+                with httpx.Client(timeout=5.0) as client:
+                    # The mounted FastMCP app is at root, its internal default path is /mcp
+                    client.get("http://localhost:8080/mcp/")
+            except httpx.RequestError:
+                pass
+            time.sleep(1)
+
+    finally:
+        if process:
+            if process.poll() is None:
+                process.terminate()
+            try:
+                _, captured_stderr = process.communicate(timeout=10)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                _, captured_stderr = process.communicate()
+
+        if os.path.exists(tmp_script_path):
+            os.unlink(tmp_script_path)
+
+    assert captured_stderr is not None, "stderr should have been captured"
+    normalized_stderr = captured_stderr.replace("\r\n", "\n").replace("\r", "\n")
+
+    assert (
+        "FastMCP's StreamableHTTPSessionManager task group was not initialized"
+        in normalized_stderr
+    )
+    assert "lifespan=mcp_app.lifespan" in normalized_stderr
+    assert "gofastmcp.com/deployment/asgi" in normalized_stderr
+    assert "Original error: Task group is not initialized" in normalized_stderr

src/fastmcp/server/http.py

@@ -306,7 +306,26 @@ def create_streamable_http_app(
     async def handle_streamable_http(
         scope: Scope, receive: Receive, send: Send
     ) -> None:
-        await session_manager.handle_request(scope, receive, send)
+        try:
+            await session_manager.handle_request(scope, receive, send)
+        except RuntimeError as e:
+            if "Task group is not initialized" in str(e):
+                new_error_message = (
+                    "FastMCP's StreamableHTTPSessionManager task group was not initialized. "
+                    "This commonly occurs when the FastMCP application's lifespan is not "
+                    "passed to the parent ASGI application (e.g., FastAPI or Starlette). "
+                    "Please ensure you are setting `lifespan=mcp_app.lifespan` in your "
+                    "parent app's constructor, where `mcp_app` is the application instance "
+                    "returned by `fastmcp_instance.http_app()`. \\n"
+                    "For more details, see the FastMCP ASGI integration documentation: "
+                    "https://gofastmcp.com/deployment/asgi"
+                )
+                # Raise a new RuntimeError that includes the original error's message
+                # for full context, but leads with the more helpful guidance.
+                raise RuntimeError(f"{new_error_message}\\nOriginal error: {e}") from e
+            else:
+                # Re-raise other RuntimeErrors if they don't match the specific message
+                raise
 
     # Get auth middleware and routes
     auth_middleware, auth_routes, required_scopes = setup_auth_middleware_and_routes(