fix(stdio): handle BrokenResourceError in stdout_reader race (#1960) by ddullah · Pull Request #2450 · modelcontextprotocol/python-sdk · GitHub

Summary

Fixes #1960. Paired with #2449 (the matching [v1.x] backport).

stdio_client has a shutdown race: read_stream_writer.aclose() in the
context's finally block can close the receiver while the background
stdout_reader task is mid-send. anyio raises BrokenResourceError,
which the outer except does not cover (ClosedResourceError is the
sibling class, raised on already-closed streams, not streams closed
during an in-flight send). The exception propagates through the task
group as ExceptionGroup and fails every caller that exits the context
while the subprocess is still writing to stdout.

Trigger

Any MCP server that writes a burst of output (startup banners, log-level
notifications/message frames, scheduler init messages, etc.) paired with
a caller that opens a short-lived stdio_client per invocation. The task
group exits before the subprocess drains, and the race fires.

Reproduced against jules-mcp-server — which emits three
notifications/message frames on init — driven by mcp2cli. Every tool
call surfaced as:

```
ExceptionGroup: unhandled errors in a TaskGroup (1 sub-exception)
+-+---------------- 1 ----------------
| Traceback (most recent call last):
| File '.../mcp/client/stdio/init.py', line 162, in stdout_reader
| await read_stream_writer.send(session_message)
| File '.../anyio/streams/memory.py', line 213, in send_nowait
| raise BrokenResourceError
| anyio.BrokenResourceError
```

Fix

Wrap both read_stream_writer.send(...) sites in stdout_reader with
try/except (ClosedResourceError, BrokenResourceError): return, and
widen the outer except to the same union for defense in depth.
stdout_reader now shuts down cleanly no matter how abruptly the caller
exits the context. No API changes.

Alternative considered

#1960 also suggests tg.cancel_scope.cancel() before the stream closes in
finally. That works but changes shutdown ordering (cancels user-defined
notification handlers, etc.). The chosen fix is narrower: treat the
shutdown race as a graceful exit from stdout_reader specifically, without
altering the task group lifecycle.

Tests

Added test_stdio_client_exits_cleanly_while_server_still_writing in
tests/client/test_stdio.py. Spawns a subprocess that writes a thousand
valid JSONRPC notifications, exits the stdio_client context immediately,
asserts no exception propagates. Wrapped in anyio.fail_after(5.0) per
AGENTS.md. Fails before the fix (ExceptionGroup / BrokenResourceError),
passes after.

Closes #1960.

`stdio_client` has a race: `read_stream_writer.aclose()` in the context's `finally` block can close the receiver while the background `stdout_reader` task is mid-`send`. anyio then raises `BrokenResourceError`, which the outer `except` does not cover (`ClosedResourceError` is the sibling class, raised on already-closed streams, not streams closed during an in-flight send). The exception propagates through the task group as `ExceptionGroup` and fails every caller that exits the context while the subprocess is still writing to stdout. Wrap both `read_stream_writer.send(...)` sites in `try`/`except (ClosedResourceError, BrokenResourceError): return` so `stdout_reader` shuts down cleanly, and widen the outer `except` to the same union for defense in depth. No API changes. Adds `test_stdio_client_exits_cleanly_while_server_still_writing`: spawns a subprocess that emits a burst of JSONRPC notifications, exits the `stdio_client` context immediately, and asserts no exception propagates. Fails before the fix (ExceptionGroup / BrokenResourceError), passes after. Github-Issue:#1960

Pull request overview

Fixes a shutdown race in stdio_client where the background stdout_reader task could raise anyio.BrokenResourceError (propagating as an ExceptionGroup) if the context exits while an in-flight send() is happening.

Changes:

Catch anyio.BrokenResourceError (alongside ClosedResourceError) around both read_stream_writer.send(...) call sites in stdout_reader, plus widen the outer handler.
Add a regression test that exits the stdio_client context while a subprocess is still producing stdout output, asserting the context exits cleanly.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/mcp/client/stdio.py	Makes stdout_reader resilient to stream-closure races by treating ClosedResourceError/BrokenResourceError as a graceful shutdown signal.
tests/client/test_stdio.py	Adds a regression test to ensure fast context exit during server output no longer fails via ExceptionGroup/BrokenResourceError.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Thanks for this — the diagnosis and fix are right. I couldn't push to your branch (org-owned fork), so I've left the simplifications as suggestions you can apply directly.

Summary:

The outer except already covers both send() calls, so the inner try/except blocks aren't needed — widening the outer one is the whole fix. Dropping them also lets us remove the # pragma: lax no cover since the new test now hits that line directly.
Reworked the test to wait on read_stream.statistics().tasks_waiting_send so we know stdout_reader is actually parked in send() before exiting — deterministic across platforms and avoids the terminate-timeout path.

AI Disclaimer

Suggested change

      
                                        try:
          
                                            await read_stream_writer.send(exc)
          
                                        except (anyio.ClosedResourceError, anyio.BrokenResourceError):
          
                                            return
          
                                        await read_stream_writer.send(exc)

Suggested change

      
                                    try:
          
                                        await read_stream_writer.send(session_message)
          
                                    except (anyio.ClosedResourceError, anyio.BrokenResourceError):
          
                                        # The caller exited the stdio_client context while the
          
                                        # subprocess was still writing; the reader stream has been
          
                                        # closed (ClosedResourceError) or the closure raced our
          
                                        # in-flight send (BrokenResourceError). Either way there
          
                                        # is nowhere to deliver this message, so shut down
          
                                        # cleanly. Fixes #1960.
          
                                        return
          
                    except (anyio.ClosedResourceError, anyio.BrokenResourceError):  # pragma: lax no cover
          
                                    await read_stream_writer.send(session_message)
          
                    except (anyio.ClosedResourceError, anyio.BrokenResourceError):
          
                        # BrokenResourceError: read_stream (receiver) was closed during cleanup while
          
                        # send() was blocked waiting for a consumer.

Suggested change

      
            async def test_stdio_client_exits_cleanly_while_server_still_writing():
          
                """Regression test for #1960.
          
                Exiting the ``stdio_client`` context while the subprocess is still writing to
          
                stdout used to surface ``anyio.BrokenResourceError`` through the task group
          
                (as an ``ExceptionGroup``). The ``finally`` block closes
          
                ``read_stream_writer`` while the background ``stdout_reader`` task is
          
                mid-``send``.
          
                The fix makes ``stdout_reader`` catch both ``ClosedResourceError`` and
          
                ``BrokenResourceError`` and return cleanly, so exiting the context is a
          
                no-op no matter what the subprocess is doing.
          
                """
          
                # A server that emits a large burst of valid JSON-RPC notifications without
          
                # ever reading stdin. When we exit the context below, the subprocess is
          
                # still in the middle of that burst, which is the exact shape of the race.
          
                noisy_script = textwrap.dedent(
          
                    """
          
                    import sys
          
                    for i in range(1000):
          
                        sys.stdout.write(
          
                            '{"jsonrpc":"2.0","method":"notifications/message",'
          
                            '"params":{"level":"info","data":"line ' + str(i) + '"}}\\n'
          
                        )
          
                        sys.stdout.flush()
          
                    """
          
                )
          
                server_params = StdioServerParameters(command=sys.executable, args=["-c", noisy_script])
          
                # The ``async with`` must complete without an ``ExceptionGroup`` /
          
                # ``BrokenResourceError`` propagating. ``anyio.fail_after`` prevents a
          
                # regression from hanging CI.
          
                with anyio.fail_after(5.0):
          
                    async with stdio_client(server_params) as (_, _):
          
                        pass
          
            async def test_stdio_client_exits_cleanly_with_unread_server_output():
          
                """Exiting the stdio_client context while stdout_reader is blocked in send() must
          
                not raise. Cleanup closes read_stream (the receiver) first, which wakes the
          
                blocked send() with BrokenResourceError; stdout_reader should swallow it.
          
                """
          
                script = textwrap.dedent(
          
                    """
          
                    import sys
          
                    sys.stdout.write('{"jsonrpc":"2.0","method":"notifications/message","params":{}}\\n')
          
                    sys.stdout.flush()
          
                    sys.stdin.read()
          
                    """
          
                )
          
                server_params = StdioServerParameters(command=sys.executable, args=["-c", script])
          
                with anyio.fail_after(5.0):
          
                    async with stdio_client(server_params) as (read_stream, _):
          
                        # Wait until stdout_reader is parked inside send() on the zero-buffer
          
                        # stream. statistics() makes this a positive check rather than a sleep.
          
                        while read_stream.statistics().tasks_waiting_send == 0:
          
                            await anyio.sleep(0)

Thanks for the PR. This has since landed via #2773. Closing as part of a general backlog cleanup following the v2 release. If this is still relevant against v2, feel free to reopen.

AI Disclaimer

Copilot AI review requested due to automatic review settings April 15, 2026 14:11

Copilot started reviewing on behalf of ddullah April 15, 2026 14:12 View session

ddullah mentioned this pull request Apr 15, 2026

BrokenResourceError race condition in stdio_client cleanup when context exits quickly #1960

Closed

Copilot AI reviewed Apr 15, 2026

View reviewed changes

maxisbey requested changes Apr 16, 2026

View reviewed changes

This was referenced May 18, 2026

Handle BrokenResourceError in stdio client shutdown path #2143

Closed

Fix stdio_client BrokenResourceError race condition during shutdown #2268

Closed

Handle BrokenResourceError in stdio client stdout reader #2567

Closed

maxisbey closed this Jul 29, 2026

fix(stdio): handle BrokenResourceError in stdout_reader race (#1960) by ddullah · Pull Request #2450 · modelcontextprotocol/python-sdk · GitHub

Uh oh!

fix(stdio): handle BrokenResourceError in stdout_reader race (#1960) - #2450

fix(stdio): handle BrokenResourceError in stdout_reader race (#1960)#2450
ddullah wants to merge 1 commit into
modelcontextprotocol:mainfrom
TigerEye-Enterprise:fix/stdio-client-broken-resource-1960-main

ddullah commented Apr 15, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

maxisbey left a comment

Uh oh!

maxisbey Apr 16, 2026

Uh oh!

maxisbey Apr 16, 2026

Uh oh!

maxisbey Apr 16, 2026

Uh oh!

maxisbey commented Jul 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fix(stdio): handle BrokenResourceError in stdout_reader race (#1960) by ddullah · Pull Request #2450 · modelcontextprotocol/python-sdk · GitHub

Uh oh!

fix(stdio): handle BrokenResourceError in stdout_reader race (#1960) - #2450

Conversation

ddullah commented Apr 15, 2026

Summary

Trigger

Fix

Alternative considered

Tests

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

maxisbey left a comment

Choose a reason for hiding this comment

Uh oh!

maxisbey Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

maxisbey Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

maxisbey Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

maxisbey commented Jul 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants