docs: Add troubleshooting guide for MCP ENAMETOOLONG error on macOS #8389
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add troubleshooting section for 'spawn ENAMETOOLONG' error on macOS - Include workaround using full command paths instead of PATH resolution - Reference related GitHub issues #7870 and #6699 - Update table of contents to include new section Generated with Continue (https://continue.dev) Co-Authored-By: Continue <[email protected]>
bdougie
requested review from
Patrick-Erichsen
and removed request for
a team
dosubot
bot
added
the
size:S
|
✅ Review Complete Code Review Summary |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Patrick-Erichsen
approved these changes
Oct 23, 2025
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds documentation to help users work around the 'spawn ENAMETOOLONG' error that occurs when connecting to MCP servers on macOS.
Problem
When Continue spawns MCP server processes on macOS, it copies the entire process environment which can exceed system limits, causing an ENAMETOOLONG error. This particularly affects users with large development environments.
Solution
Document the workaround of using full command paths (e.g.,
/usr/local/bin/npx) instead of relying on PATH resolution.Changes
Related Issues
Testing
Notes
While this PR provides immediate help through documentation, a proper code fix is still needed to filter environment variables when spawning MCP processes. See the discussion in #7870 for implementation details.
Summary by cubic
Adds a troubleshooting guide for MCP server connection issues on macOS, documenting the "spawn ENAMETOOLONG" error caused by large environments when spawning MCP processes. Explains the workaround to use full command paths (e.g., /usr/local/bin/npx) instead of PATH, and links to related issues (#7870, #6699).