fix(stdio): handle BrokenResourceError in stdout_reader race (#1960)#2450
Conversation
`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:modelcontextprotocol#1960
There was a problem hiding this comment.
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(alongsideClosedResourceError) around bothread_stream_writer.send(...)call sites instdout_reader, plus widen the outer handler. - Add a regression test that exits the
stdio_clientcontext 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.
maxisbey
left a comment
There was a problem hiding this comment.
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
exceptalready covers bothsend()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 coversince the new test now hits that line directly. - Reworked the test to wait on
read_stream.statistics().tasks_waiting_sendso we knowstdout_readeris actually parked insend()before exiting — deterministic across platforms and avoids the terminate-timeout path.
| try: | ||
| await read_stream_writer.send(exc) | ||
| except (anyio.ClosedResourceError, anyio.BrokenResourceError): | ||
| return |
There was a problem hiding this comment.
| try: | |
| await read_stream_writer.send(exc) | |
| except (anyio.ClosedResourceError, anyio.BrokenResourceError): | |
| return | |
| await read_stream_writer.send(exc) |
| 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 |
There was a problem hiding this comment.
| 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. |
| 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 |
There was a problem hiding this comment.
| 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) |
Summary
Fixes #1960. Paired with #2449 (the matching
[v1.x]backport).stdio_clienthas a shutdown race:read_stream_writer.aclose()in thecontext's
finallyblock can close the receiver while the backgroundstdout_readertask is mid-send. anyio raisesBrokenResourceError,which the outer
exceptdoes not cover (ClosedResourceErroris thesibling class, raised on already-closed streams, not streams closed
during an in-flight send). The exception propagates through the task
group as
ExceptionGroupand fails every caller that exits the contextwhile the subprocess is still writing to stdout.
Trigger
Any MCP server that writes a burst of output (startup banners, log-level
notifications/messageframes, scheduler init messages, etc.) paired witha caller that opens a short-lived
stdio_clientper invocation. The taskgroup exits before the subprocess drains, and the race fires.
Reproduced against
jules-mcp-server— which emits threenotifications/messageframes on init — driven bymcp2cli. Every toolcall 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 instdout_readerwithtry/except (ClosedResourceError, BrokenResourceError): return, andwiden the outer
exceptto the same union for defense in depth.stdout_readernow shuts down cleanly no matter how abruptly the callerexits the context. No API changes.
Alternative considered
#1960 also suggests
tg.cancel_scope.cancel()before the stream closes infinally. That works but changes shutdown ordering (cancels user-definednotification handlers, etc.). The chosen fix is narrower: treat the
shutdown race as a graceful exit from
stdout_readerspecifically, withoutaltering the task group lifecycle.
Tests
Added
test_stdio_client_exits_cleanly_while_server_still_writingintests/client/test_stdio.py. Spawns a subprocess that writes a thousandvalid JSONRPC notifications, exits the
stdio_clientcontext immediately,asserts no exception propagates. Wrapped in
anyio.fail_after(5.0)perAGENTS.md. Fails before the fix (ExceptionGroup / BrokenResourceError),
passes after.
Closes #1960.