anthropics / anthropics/claude-agent-sdk-python
EINTR errors in file watcher cause MCP initialization timeout
- Dominant language
- Python
- Stars
- 8.1k
- Forks
- 1.3k
- Avg merge
- 2d 31m
- Merged PRs (30d)
- 1
Description
## Summary
MCP server initialization times out due to unhandled `EINTR` (interrupted system call) errors in the bundled Node.js CLI's file watcher. This causes sessions to crash and enter a timeout/recovery loop.
## Environment
- **OS**: macOS 15.2 (Darwin 25.2.0)
- **Python**: 3.13
- **SDK version**: Latest (installed via pip)
- **MCP tools registered**: 68 custom tools
## Error logs
```
Exception: Control request timeout: initialize
This error originated either by throwing inside of an async function without a catch block,
or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason:
Error: EINTR: interrupted system call, watch '/var/folders/h4/.../T/...-IBTOOLD-IN.QnhTSAefXh'
at watch (unknown)
at new FSWatcher (node:fs:29:31)
at watch (node:fs:296:23)
```
## Impact
- Every session eventually hits the 60-second initialization timeout
- Sessions enter an infinite timeout → recovery → timeout loop
- The application becomes unusable for multi-turn conversations
## Root cause analysis
The bundled CLI subprocess uses file watchers for IPC. When a system signal interrupts the `watch()` syscall, Node.js throws an `EINTR` error. This error is not caught/retried, causing the initialization to hang until it times out.
## Expected behavior
`EINTR` is a standard Unix signal indicating a syscall was interrupted and should be retried. The file watcher should:
1. Catch `EINTR` errors
2. Retry the watch operation
3. Not propagate the error up as a fatal failure
## Workaround
Setting `CLAUDE_CODE_STREAM_CLOSE_TIMEOUT=180000` (3 minutes) gives more time for initialization to eventually succeed, but doesn't fix the underlying issue.
## Reproduction
1. Create an MCP server with ~50+ tools
2. Use `ClaudeSDKClient` in a long-running server process
3. Send multiple messages over time
4. Observe `Control request timeout: initialize` errors in logs
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by locating the bundled Node.js CLI's file watcher used for IPC and reproduce the EINTR failure during MCP initialization on macOS. Trace the watch operation that emits the logged error and verify that interrupted calls are retried without causing the initialize control request to time out.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, python
- Domain
- backend, cli
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100