modelcontextprotocol / modelcontextprotocol/python-sdk

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

Open
#2,454 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug fix proposed P2 ready for work
Dominant language
Python
Stars
24.3k
Forks
4k
Avg merge
1d 1h
Merged PRs (30d)
31

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in mcp.client.stdio.stdio_client() and tests/client/test_stdio.py; review how TextReceiveStream decoding and read-stream iteration handle encoding errors. Add the malformed-then-valid regression described in the issue, then run the focused test to verify the first item is an Exception, the second a valid SessionMessage, and the transport remains alive.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend, testing
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.