ExceptionGroup wrapping obscures real errors from task groups

[maxisbey]

Summary

When SDK internal anyio task group tasks fail, the real error is wrapped in a BaseExceptionGroup alongside Cancelled exceptions from cancelled sibling tasks. This makes error classification extremely difficult for callers — they cannot reliably determine the root cause of a failure.

There are 16 create_task_group() usages across the SDK with no except* syntax or ExceptionGroup unwrapping anywhere.

Expected Behavior

• Callers should receive the original exception, not an ExceptionGroup wrapping it alongside cancellation noise
• When a task group has one real failure and N cancelled siblings, only the real failure should propagate

Current Behavior

• A single connection failure produces a BaseExceptionGroup containing the real error plus multiple Cancelled exceptions
• Callers must manually unwrap exception groups to find the root cause
• This affects ~80+ call sites across the SDK where task groups are used

Affected Code

• src/mcp/shared/session.py (session task groups)
• src/mcp/client/streamable_http.py (transport task groups)
• All other create_task_group() sites

Related

• Introduce typed error classes with metadata #1742 — broader typed error classes design
• CancelledError from connection failures is indistinguishable from external cancellation #1830 — CancelledError indistinguishable from external cancellation (closed but related)

---

_{AI Disclaimer}

[zhiyuanliang-ms]

This is a real pitfall in the Python MCP SDK: a connection/setup failure can surface to callers as CancelledError(BaseException) rather than as the underlying transport error, which makes simple wrappers around asyncio.wait_for() surprisingly brittle.

We hit this with MCPStreamableHTTPTool.connect(). A normal except TimeoutError / except Exception handler was not enough; we had to add a BaseException branch to see what was actually escaping. In our case, the outer observable error was CancelledError, while the underlying failure was an HTTP transport error during connection setup.

import asyncio
import time

from agent_framework import MCPStreamableHTTPTool

URL = "https://custom-mcp-server.com"


async def wait_for_connect():
    tool = MCPStreamableHTTPTool(
        name="geneva-action",
        url=URL,
        request_timeout=10,
    )

    t0 = time.monotonic()
    try:
        await asyncio.wait_for(tool.connect(), timeout=5.0)
        print(f"Connected in {time.monotonic() - t0:.1f}s")

    except TimeoutError as e:
        print(f"TimeoutError after {time.monotonic() - t0:.1f}s: {type(e).__name__}: {e!r}")

    except Exception as e:
        print(f"Exception after {time.monotonic() - t0:.1f}s: {type(e).__name__}: {e!r}")

    except BaseException as e:
        # Without this, the escaping cancellation path is easy to miss.
        print(f"BaseException after {time.monotonic() - t0:.1f}s: {type(e).__name__}: {e!r}")

    finally:
        print(f"Total elapsed: {time.monotonic() - t0:.1f}s")


async def main():
    await wait_for_connect()
    print("Done!")


asyncio.run(main())

[tsingh2k15]

Ran into this while integrating with Snowflake's managed MCP server over Streamable HTTP. I concur that The SDK should unwrap ExceptionGroup internally before propagating, or expose typed error classes so callers don't need to inspect exception internals at all. A typed error surface (as proposed in #1742) would make overall handling much cleaner.

Environment

• mcp 1.26.0
• Python 3.14.2
• Transport: streamablehttp_client → Snowflake managed MCP

streamablehttp_client and ClientSession both use create_task_group() internally. A single connection failure (e.g. auth rejection, network timeout) produces something like:

BaseExceptionGroup: unhandled errors in a TaskGroup (2 sub-exceptions)
  ├── ConnectionError: Connection refused        ← the real error
  └── anyio.get_cancelled_exc_class(): Cancelled ← noise from sibling task cleanup

Happy to test any fix or provide more detail if useful.