Fix MCP Server spawn ENOENT Error

What Is the spawn ENOENT Error?

The spawn ENOENT error is the single most common MCP server startup failure. ENOENT stands for "Error NO ENTry" - it means the operating system tried to launch a process but could not find the executable at the specified path. When your MCP client attempts to start a server, it calls child_process.spawn() with the command from your configuration. If that command does not resolve to an actual file on disk, the OS returns ENOENT and the server never starts.

The error looks different depending on which client and operating system you are using. Here is a reference of the exact messages you will see on each platform:

Error Messages by Operating System

OS	Error Message	Common Trigger
macOS	Error: spawn npx ENOENT with stack trace pointing to node:internal/child_process:284	Homebrew or nvm path not visible to GUI apps
Windows	Error: spawn npx ENOENT or spawn UNKNOWN when .cmd extension is missing	Using npx instead of npx.cmd
Linux	Error: spawn npx ENOENT with errno: -2, code: 'ENOENT', syscall: 'spawn'	nvm/fnm path not in systemd or desktop environment

Some clients wrap the error in their own format. Claude Desktop may show MCP server failed to start: spawn error ENOENT / Server exited with code 1. Cursor displays a red status indicator next to the server name in Settings. VS Code logs the full spawn error in its Output panel under the MCP channel.

This guide covers every known cause of this error, provides platform-specific fixes, and includes a config validator approach you can use to catch these problems before they happen.

Cause 1: npx or Node.js Not Found in PATH

The most frequent cause is that npx (or node) is not in the system PATH that your MCP client sees. GUI applications on macOS and Windows do not inherit your shell's PATH, so even if npx works perfectly in your terminal, the client cannot find it. This is because your terminal sources profile files like .bashrc, .zshrc, or .bash_profile on startup, but GUI applications launched from the Dock, Start Menu, or taskbar skip this step entirely.

Fix for macOS

Use the full path to npx in your MCP configuration. Find it by running:

which npx
# Typical output: /usr/local/bin/npx (Intel Mac with Node from installer)
# Typical output: /opt/homebrew/bin/npx (Apple Silicon with Homebrew)
# Typical output: /Users/you/.nvm/versions/node/v22.0.0/bin/npx (nvm)

Then update your claude_desktop_config.json to use the absolute path:

{
  "mcpServers": {
    "filesystem": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    }
  }
}

If you installed Node via Homebrew on Apple Silicon, the path is /opt/homebrew/bin/npx. On Intel Macs with Homebrew, it is /usr/local/bin/npx. If you installed Node from the official nodejs.org installer, the path is /usr/local/bin/npx regardless of CPU architecture.

Fix for Windows

On Windows, use npx.cmd instead of npx. Windows requires the .cmd extension for batch scripts when spawning child processes programmatically:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\you\\Documents"]
    }
  }
}

If that still fails, use the full path: C:\\Program Files\\nodejs\\npx.cmd. You can find the exact location by running where npx in Command Prompt. See our full Windows MCP setup guide for more Windows-specific fixes.

Fix for Linux

Linux users using nvm or fnm must provide the full path since GUI apps and systemd services do not source your .bashrc or .zshrc:

which npx
# Typical nvm output: /home/user/.nvm/versions/node/v20.11.0/bin/npx
# Typical fnm output: /home/user/.local/share/fnm/aliases/default/bin/npx
# System Node.js: /usr/bin/npx

For Linux desktop environments like GNOME or KDE, GUI applications inherit the environment from the desktop session, not from your terminal shell. If you set PATH in .bashrc, applications launched from the application menu will not see those additions. You can fix this by adding your nvm/fnm path to ~/.profile or ~/.pam_environment, which are sourced by the login manager.

Cause 2: nvm and fnm Path Resolution Issues

Node version managers like nvm and fnm are the single biggest source of ENOENT errors because they work by dynamically modifying PATH in your shell session. When a GUI application spawns a process, the version manager's initialization script never runs, so npx, node, and all globally installed packages are invisible.

nvm-Specific Fix

Find the exact path to your default Node version and use it directly:

# Find your default version
nvm which default
# Output: /home/user/.nvm/versions/node/v22.0.0/bin/node

# The npx for that version is in the same directory
# /home/user/.nvm/versions/node/v22.0.0/bin/npx

Use this absolute path in your config. When you upgrade Node via nvm, remember to update your MCP config paths as well, since the version number is part of the directory path.

Alternatively, create a stable symlink that survives version upgrades:

# Create a stable symlink
ln -sf $(nvm which default | xargs dirname)/npx /usr/local/bin/npx-mcp

# Use /usr/local/bin/npx-mcp in your MCP config
# Re-run the ln command after upgrading Node

fnm-Specific Fix

fnm stores its binaries differently from nvm. Find the path with:

fnm exec --using=default -- which npx
# Typical output: /home/user/.local/share/fnm/aliases/default/bin/npx

The aliases/default path is a symlink that updates when you change your default version, making it more stable than nvm's versioned paths.

Cause 3: Wrong Node.js Version

Some MCP servers require Node.js 18+ or 20+. If you have an older version, the server binary might not exist or may crash immediately, producing the ENOENT error. This is common when the system Node.js is an old version from the OS package manager while your terminal uses a newer version from nvm.

Node.js Version	MCP Compatibility	Notes
v14.x or older	Not supported	Missing ES module support needed by MCP SDK
v16.x	Partial	Some servers work, many do not (EOL)
v18.x	Supported	Minimum for most official servers
v20.x - v22.x	Recommended	Best compatibility and performance

node --version
# Should be v18.x or higher, ideally v20+

# If using nvm, set the default:
nvm install 22
nvm alias default 22

# If using fnm:
fnm install 22
fnm default 22

Cause 4: Python MCP Servers - Path Issues

Python-based MCP servers using uvx, uv, or python have the same PATH problem. The error looks like:

Error: spawn uvx ENOENT
Error: spawn python3 ENOENT
Error: spawn uv ENOENT

Find the full path and use it directly:

# Find uvx (installed via pipx or standalone)
which uvx
# Output: /home/user/.local/bin/uvx (Linux)
# Output: /opt/homebrew/bin/uvx (macOS with Homebrew)

# Find uv
which uv
# Output: /home/user/.cargo/bin/uv (installed via cargo)
# Output: /home/user/.local/bin/uv (installed via installer script)

which python3
# Output: /usr/bin/python3 (system Python)
# Output: /home/user/.pyenv/shims/python3 (pyenv)

Update your config accordingly:

{
  "mcpServers": {
    "my-python-server": {
      "command": "/home/user/.local/bin/uvx",
      "args": ["my-mcp-server"]
    }
  }
}

If you use pyenv for Python version management, the same GUI PATH problem applies. The pyenv shims directory (~/.pyenv/shims/) must be visible to the MCP client. Use the absolute path to the actual Python binary instead of the shim: run pyenv which python3 to get the real path.

Cause 5: Permission Errors

On macOS and Linux, the executable might exist but lack execute permissions:

ls -la $(which npx)
# Check for 'x' in permissions: -rwxr-xr-x

# Fix permissions if needed:
chmod +x $(which npx)

On macOS, you may also need to allow the binary through Gatekeeper if it is unsigned. If you see a dialog saying the app "cannot be opened because the developer cannot be verified," go to System Settings, Privacy and Security, and click "Allow Anyway" next to the blocked binary.

On Linux, if Node.js was installed via Snap, the confined Snap environment restricts filesystem access. Servers that need to read or write files outside the Snap sandbox will fail with ENOENT even though the binary exists. Consider installing Node.js via nvm or your distro's package manager instead of Snap.

Cause 6: Server Package Not Installed or Misspelled

If you are using npx -y and it fails, the package might not exist or the name might be misspelled. Test manually in your terminal:

npx -y @modelcontextprotocol/server-filesystem --help

Common misspellings and naming mistakes include:

• Using server-fs instead of server-filesystem
• Missing the @modelcontextprotocol/ scope prefix
• Using an old package name after a server was renamed
• Typos in community server names (double-check on npm or the server directory)

Check the filesystem server page or the relevant server listing for the correct package name. If npx fails with a network error, you may be behind a corporate proxy - try pre-installing the package globally with npm install -g instead.

Client-Specific Debugging

Claude Desktop

Check the Claude Desktop logs for the exact error:

OS	Log Location
macOS	~/Library/Logs/Claude/mcp*.log
Windows	%APPDATA%\Claude\logs\mcp*.log
Linux	~/.config/Claude/logs/mcp*.log

After editing claude_desktop_config.json, fully quit and relaunch Claude Desktop (not just close the window). On macOS use Cmd+Q, on Windows right-click the system tray icon and select Exit. See the Claude Desktop troubleshooting guide for complete restart procedures.

Cursor

In Cursor, check your .cursor/mcp.json file for typos. Cursor uses a slightly different config format. Open Settings, navigate to the MCP section, and look for servers with red status indicators. Click the server name to see the exact error message. If the error says ENOENT, the fix is the same - use an absolute path to the command. See the Cursor MCP error guide for more details.

VS Code

In VS Code, open the Output panel (View, Output) and select the MCP extension channel from the dropdown. The ENOENT error with the full command will be logged there. VS Code also supports configuring MCP servers in .vscode/mcp.json at the project level. Check that the command path is correct for your operating system.

Building a Config Validator

You can catch ENOENT errors before they happen by validating your MCP config. Here is a simple script that checks whether all configured commands exist and are executable:

#!/usr/bin/env node
// validate-mcp-config.js
// Usage: node validate-mcp-config.js path/to/config.json

const fs = require("fs");
const { execSync } = require("child_process");
const path = require("path");

const configPath = process.argv[2];
if (!configPath) {
  console.error("Usage: node validate-mcp-config.js ");
  process.exit(1);
}

const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
const servers = config.mcpServers || {};
let hasErrors = false;

for (const [name, server] of Object.entries(servers)) {
  const cmd = server.command;
  try {
    const which = process.platform === "win32" ? "where" : "which";
    const result = execSync(`${which} ${cmd}`, { encoding: "utf-8" }).trim();
    console.log(`[OK] ${name}: ${cmd} -> ${result}`);
  } catch {
    console.error(`[FAIL] ${name}: "${cmd}" not found in PATH`);
    console.error(`  Fix: use the full absolute path to ${cmd}`);
    hasErrors = true;
  }
}

if (hasErrors) {
  console.error("\nSome servers will fail with spawn ENOENT.");
  process.exit(1);
} else {
  console.log("\nAll server commands validated successfully.");
}

Run this validator whenever you edit your MCP configuration. It checks each server's command against the current PATH and reports which ones would fail. You can also integrate this into a pre-commit hook if your config is version-controlled.

Step-by-Step Universal Fix

1. Identify the command - Open your MCP config and note the "command" value (e.g., npx, uvx, python3).
2. Test in terminal - Run which <command> (macOS/Linux) or where <command> (Windows) to verify it exists and get the full path.
3. Use absolute path - Replace the command name with the full path in your config. For example, change "command": "npx" to "command": "/opt/homebrew/bin/npx".
4. Check permissions - Run ls -la <full-path> to verify execute permissions. Fix with chmod +x if needed.
5. Verify Node/Python version - Run <full-path> --version to confirm the runtime version meets the server's requirements.
6. Restart the client - Fully quit and relaunch your MCP client. Closing the window is not enough for most clients.
7. Check logs - If it still fails, check client-specific logs for the exact error. The log will show the full command and arguments that were attempted.

Common Pitfalls

• Using ~ in config paths - JSON configs do not expand ~. Use the full path like /Users/yourname/... or /home/yourname/....
• Forgetting .cmd on Windows - Windows requires npx.cmd, node.cmd, uvx.cmd, etc. when spawning from a non-shell context.
• nvm/fnm shell-only paths - Version managers only set PATH in your shell. GUI apps do not see them. Always use absolute paths.
• Docker containers - If running the server in Docker, the command path is inside the container, not on the host. Use "command": "docker" with appropriate run arguments.
• Snap-installed Node - Snap packages have restricted filesystem access that can cause ENOENT on certain paths. Switch to nvm or the official Node.js installer.
• Multiple Node installations - Having Node installed via both the system package manager and nvm can cause confusion. Run which -a npx to see all npx binaries on your system and pick the right one.
• Spaces in paths - Paths containing spaces (common on Windows) need proper quoting. In JSON, the path is already a string, so "C:\\Program Files\\nodejs\\npx.cmd" works correctly.
• Outdated npx cache - Sometimes npx caches a broken version of a package. Clear the cache: npx clear-npx-cache or delete the _npx directory in your npm cache folder.

If you are setting up your first MCP server, check our First MCP Server tutorial which walks through the complete setup process including avoiding this error. For environment variable issues that can also cause startup failures, see the environment variables guide.