MCP ENOENT: fix npx, uvx and command-not-found errors
MCP fails with ENOENT or command not found? Check executable paths, working directories, arguments and stdio output with a reproducible troubleshooting sequence.
What ENOENT means during MCP startup
When a client reports spawn npx ENOENT, start with local process creation. The message does not yet establish a broken MCP endpoint. In Node.js, it can refer to either a missing executable or a nonexistent working directory. Check both settings before changing anything else. Issuing a new access token will not repair an executable path that the process cannot resolve.
Check the terminal and client separately
Record the executable configured in the client. On macOS or Linux, use command -v npx; in PowerShell, use Get-Command npx to locate it. Substitute uvx, node or docker when that is the configured program. These checks describe your terminal environment. A desktop application may have inherited a different search path. Do not copy a path found on another computer without checking it locally. A locally confirmed absolute executable path is a useful controlled comparison.
Separate executable, arguments and directory
A command field and an args array describe different parts of a launch. If the entire terminal command is used as the executable name, the client may look for a file whose name includes spaces and options. Follow the format documented for your client. Also verify that the configured working directory exists and is accessible to the account running the client. Relative paths can depend on the launch directory. Windows launch files such as .cmd require the launch mechanism documented by the client.
| Observation | Check |
|---|---|
| ENOENT despite installed package | Client executable path and working directory |
| Terminal launch succeeds | Compare desktop application environment |
| JSON error after startup | Check wrapper output on stdout |
Check the protocol after startup
Once ENOENT disappears, make a separate check: does initialization succeed? A running process is not sufficient evidence. For stdio, stdout must carry only protocol messages; ordinary diagnostics belong on stderr. If the process exits immediately, inspect the first message and the exit code. A terminal process waiting for input has not necessarily stalled. Record process startup and successful protocol initialization as separate outcomes, so that a later connection failure does not obscure the path problem you already resolved.
Keep a local copy of the previous file and record the first error.
Change one launch setting and reload the client.
Check initialization and the tool list before running an application operation.
Use the troubleshooting navigator for other symptoms and their next checks. The configuration builder helps compare formats. Use the registry comparison when similarly named entries declare different packages or launch paths. A registry declaration describes its source; it does not replace your connection test.
- Should I reinstall the package?
- Not as the first step. Check whether the client can locate its executable and working directory.
- Does stderr mean failure?
- No. Ordinary diagnostics may be written there; read the message together with the exit code.
- Why does the same command work in a terminal?
- The terminal may have a different search path and environment from the desktop application. Compare both launch environments.
- What should I check after startup succeeds?
- Check MCP initialization and then the tool list. Test the required operation after those checks succeed.
Sources checked on 1 October 2026. The checks are editorial suggestions for your environment.
- Node.js: Child process
Show retrieval command
curl -s https://nodejs.org/api/child_process.html - MCP: Debugging
Show retrieval command
curl -s https://modelcontextprotocol.io/docs/tools/debugging - MCP 2025-11-25: Transports
Show retrieval command
curl -s https://modelcontextprotocol.io/specification/2025-11-25/basic/transports