History

Every saved version of bugs/mcp-body-stream-locked.md, newest first. Each row shows what changed compared to the version before it.

• v1currentCreatedby agent · 18d ago
  Initial content

  # MCP: ReadableStream locked between fetch-to-node and Hono's c.req.json()
  
  ## Symptom
  
  The remote MCP route handled `initialize` cleanly:
  
  ```
  event: message
  data: {"result":{"protocolVersion":"2025-03-26", ...}}
  ```
  
  But `tools/list` returned a Railway edge 502:
  
  ```
  {"status":"error","code":502,"message":"Application failed to respond"}
  ```
  
  Railway logs showed:
  
  ```
  TypeError [ERR_INVALID_STATE]: Invalid state: ReadableStream is locked
    at FetchIncomingMessage._read (.../fetch-to-node/.../http-incoming.js:169:37)
  ```
  
  ## Root cause
  
  The route handler was:
  
  ```ts
  const { req, res } = toReqRes(c.req.raw);   // wraps Web Request as Node IncomingMessage
  const body = await c.req.json();             // Hono reads c.req.raw.body via .getReader()
  await transport.handleRequest(req, res, body);
  ```
  
  `c.req.json()` locks the Web Request's body `ReadableStream` (Hono calls `getReader()` internally). When the SDK transport's `handleRequest` later calls `req._read()` on the fetch-to-node-wrapped IncomingMessage, it tries to call `getReader()` on the same (now locked) stream and throws.
  
  `initialize` worked because the SDK's protocol path for `initialize` apparently doesn't re-touch the request body after the initial parse — only `tools/list` (and most other methods) did. So `initialize` looked fine while everything else 502'd.
  
  ## Fix
  
  `Request.clone()` gives an independent body stream:
  
  ```ts
  const cloned = c.req.raw.clone();
  const body = await c.req.json();         // reads original stream — locks original
  const { req, res } = toReqRes(cloned);   // wraps clone — independent body, not locked
  await transport.handleRequest(req, res, body);
  ```
  
  Commit: `86e00f7` (`fix(mcp): clone Web Request before fetch-to-node bridge`).
  
  ## What made it hard to spot
  
  - **`initialize` succeeded.** The smoke test passed on the first request and the obvious failure mode (transport unwired) was ruled out. The bug felt protocol-specific, not stream-specific.
  - **The stack trace pointed at `FetchIncomingMessage._read`** — inside `fetch-to-node`, a dependency. Easy to suspect the bridge itself rather than the order of Hono calls upstream.
  - **The 502 came from Railway's edge**, not the Node process. The actual Node trace was buried in Railway logs, two clicks deep.
  - **The reference implementation** (`mhart/mcp-hono-stateless`) uses the exact same order — `toReqRes(c.req.raw)` then `await c.req.json()` — so a code comparison didn't surface the issue. The reference might be running an older fetch-to-node where this happened to work; or it has the same latent bug for methods other than initialize.
  
  Lesson: Web Request bodies are single-reader streams. Anything that calls `.body.getReader()` (Hono's `.json()`, `.text()`, etc.) locks them. Pass a clone to libraries that wrap the underlying stream — never both touch the original.