stdio_client crashes on malformed UTF-8 from child stdout instead of surfacing parse error

[shaun0927]

Summary

mcp.client.stdio.stdio_client() crashes when the spawned child process writes invalid UTF-8 bytes to stdout.

The transport currently decodes child stdout with encoding_error_handler="strict", so malformed bytes raise during TextReceiveStream(...) iteration. That exception escapes the decoding loop and brings down the transport task group instead of surfacing the bad line as an in-stream parse error.

Why this looks like a bug

The SDK already hardened the server side for the analogous case in PR #2302 (fix: handle non-UTF-8 bytes in stdio server stdin). That change explicitly preferred:

• replace invalid bytes with U+FFFD,
• let JSON validation fail on the malformed line, and
• keep the transport alive so subsequent valid messages can still be processed.

The client side still behaves asymmetrically today. A buggy or non-compliant child server can kill the Python client transport with a single malformed line even if the next line is valid JSON-RPC.

That seems inconsistent with the current stdio robustness direction.

Reproduction

A minimal child process that writes one malformed line and then one valid JSON-RPC line:

import sys
import time

sys.stdout.buffer.write(b"\xff\xfe\n")
sys.stdout.buffer.write(b'{"jsonrpc":"2.0","id":1,"method":"ping"}\n')
sys.stdout.buffer.flush()
time.sleep(0.2)

With current stdio_client(...) defaults, the transport raises ExceptionGroup instead of continuing.

Expected behavior

The malformed line should be surfaced as an in-stream parse / validation error, and the next valid JSON-RPC line should still be received.

Observed behavior

The transport task group fails before the valid follow-up message is delivered.

Proposed fix

Match the server-side approach from PR #2302:

1. default StdioServerParameters.encoding_error_handler to "replace"
2. continue treating malformed decoded lines as JSON validation failures
3. keep the background stdio tasks resilient during early subprocess shutdown / abrupt close

Validation

I reproduced this locally against current main and verified that a minimal patch plus a regression test fixes it.

A focused regression test in tests/client/test_stdio.py can assert:

• first item from the read stream is an Exception
• second item is the valid SessionMessage

[mcp-claude]

confirmed reproduced on both main (3d7b311) and v1.x (73d458b).

root cause: StdioServerParameters.encoding_error_handler defaults to "strict" (src/mcp/client/stdio.py:95). a single invalid UTF-8 byte from the child raises UnicodeDecodeError inside TextReceiveStream at line 143; stdout_reader() doesn't catch it, so the task group tears down the entire transport as an ExceptionGroup. the server side already defaults to "replace" (PR #2302); the client was missed.

fix: change the default at line 95 from "strict" to "replace" — one line, no API break, matches existing server behavior.

workaround: pass encoding_error_handler="replace" explicitly when constructing StdioServerParameters.

repro script

# repro.py — run with: uv run python repro.py
import asyncio
import sys
import textwrap
import tempfile
import os

import anyio

CHILD_SCRIPT = textwrap.dedent("""\
    import sys, time
    sys.stdout.buffer.write(b"\\xff\\xfe\\n")
    sys.stdout.buffer.write(b'{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"ping\"}\\n')
    sys.stdout.buffer.flush()
    time.sleep(0.5)
""")

async def main():
    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
        f.write(CHILD_SCRIPT)
        child_path = f.name
    try:
        from mcp.client.stdio import stdio_client, StdioServerParameters
        params = StdioServerParameters(command=sys.executable, args=[child_path])
        print(f"encoding_error_handler = {params.encoding_error_handler!r}")
        items = []
        try:
            async with stdio_client(params) as (read_stream, write_stream):
                async with anyio.fail_after(3.0):
                    async for item in read_stream:
                        items.append(item)
                        if len(items) >= 2:
                            break
        except BaseException as e:
            print(f"\nCRASH: {type(e).__name__}: {e}")
        print(f"Total items received: {len(items)}")
    finally:
        os.unlink(child_path)

anyio.run(main)

terminal output

$ uv run python repro.py
encoding_error_handler = 'strict'

CRASH: ExceptionGroup: unhandled errors in a TaskGroup (1 sub-exception)

Total items received: 0

code path

• src/mcp/client/stdio.py:143 — TextReceiveStream(process.stdout, encoding="utf-8", errors="strict") raises UnicodeDecodeError on \xff\xfe
• src/mcp/client/stdio.py:161 — only anyio.ClosedResourceError is caught; UnicodeDecodeError escapes the task
• src/mcp/client/stdio.py:180 — anyio.create_task_group() wraps it in ExceptionGroup and cancels the transport
• fix target: src/mcp/client/stdio.py:95 — change default "strict" → "replace"

suggested fix

# src/mcp/client/stdio.py
-    encoding_error_handler: Literal["strict", "ignore", "replace"] = "strict"
+    encoding_error_handler: Literal["strict", "ignore", "replace"] = "replace"

test to verify: assert params.encoding_error_handler == "replace" by default, and that stdio_client exits cleanly (no ExceptionGroup) when a child writes b"\xff\xfe\n" to stdout.

[shaun0927]

thanks for the independent reproduction and analysis. the suggested one-line default change matches PR #2456 (already open with the same fix + a regression test). PR is green across the matrix and ready for review whenever a maintainer has cycles.