Fix: Tool Execution Failed (Exit Code 127)

Error Message:

"Tool execution failed with exit code 127" "/bin/sh: python: command not found" "/bin/sh: npm: command not found" "/bin/sh: 1: rg: not found" "command not found" (followed by the tool name Claude tried to run)

What This Error Means

Exit code 127 is the shell's way of saying "I couldn't find the command you tried to run." The binary isn't on the PATH that Claude's shell environment has access to. This is not a permissions error (that's 126), not a syntax error (that's 2), and not a general failure (that's 1). It specifically means the executable doesn't exist in any directory listed in the current PATH environment variable.

Root Cause Analysis

Claude Cowork executes commands in a non-interactive, non-login shell — typically /bin/sh or /bin/bash invoked without the -l (login) or -i (interactive) flags. This matters because your shell's PATH and environment are set up by startup files that only load in specific modes:

  • .bash_profile / .zprofile — loaded only by login shells
  • .bashrc / .zshrc — loaded only by interactive shells
  • .profile — loaded by login shells (if no .bash_profile exists)

When Claude runs sh -c "npm install", none of these files are sourced. The shell starts with a minimal PATH — often just /usr/bin:/bin — and has no knowledge of tools installed by version managers (nvm, pyenv, rbenv), Homebrew (/opt/homebrew/bin), or custom entries you added to your .zshrc.

The most common victims are:

  • Node.js — installed via nvm, which adds to PATH in .zshrc/.bashrc. Claude's shell sees the system Node (if any) or nothing.
  • Python — installed via pyenv or conda. Same issue: the shim directory isn't on PATH.
  • Homebrew tools — rg, jq, tree, gh all live in /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel), which may not be in the minimal PATH.
  • Go binaries — installed to ~/go/bin via go install, which is almost never in the default PATH.

A second, subtler cause is version mismatch. Even when a tool is found, it might be the wrong version. If the system has Node 16 at /usr/bin/node and you installed Node 20 via nvm at ~/.nvm/versions/node/v20.10.0/bin/node, Claude's shell might find the system Node 16 first (because /usr/bin is on the minimal PATH) and run commands against the wrong version. This produces errors like "SyntaxError: Unexpected token" when Claude's code uses features that require Node 20.

Real-World Scenario

You ask Claude to run the test suite. It executes npm test, and the shell returns exit code 127: npm: command not found. You know npm works — you ran npm test yourself five minutes ago in your terminal. The difference: your terminal is an interactive zsh session that sourced .zshrc, which loaded nvm, which put ~/.nvm/versions/node/v20.10.0/bin on your PATH. Claude's shell is /bin/sh with PATH=/usr/bin:/bin, and npm isn't there.

Step-by-Step Fix

Step 1: Find where the tool actually lives

Run this in your own terminal (the interactive one where things work):

which node
which npm
which python3
# Or for any tool:
which <toolname>

Note the full paths. For example:

/Users/you/.nvm/versions/node/v20.10.0/bin/node
/Users/you/.nvm/versions/node/v20.10.0/bin/npm
/opt/homebrew/bin/python3

Step 2: Tell Claude to use absolute paths

Give Claude the full path directly:

"npm is located at /Users/you/.nvm/versions/node/v20.10.0/bin/npm. 
Use that full path for all npm commands. Run the tests with:
/Users/you/.nvm/versions/node/v20.10.0/bin/npm test"

Step 3: Or, set PATH inline for each command

If you don't want to use absolute paths for every command, prepend a PATH export:

export PATH="/Users/you/.nvm/versions/node/v20.10.0/bin:/opt/homebrew/bin:$PATH" && npm test

Tell Claude:

"Before running any Node or Python commands, run:
export PATH=\"/Users/you/.nvm/versions/node/v20.10.0/bin:/opt/homebrew/bin:$PATH\"
Then use npm, node, python3 normally."

Step 4: Configure a persistent environment (long-term fix)

Most Claude Cowork setups let you define environment variables for the project. Create or edit a .env file in your project root (or use the platform's settings UI):

# .env
PATH=/Users/you/.nvm/versions/node/v20.10.0/bin:/opt/homebrew/bin:/usr/bin:/bin

This ensures every shell Claude spawns starts with the correct PATH. Check your platform's documentation for the exact env file location and format.

Step 5: Verify the fix

Ask Claude to run a diagnostic:

which node && node --version && which npm && npm --version

Confirm the output shows the correct paths and versions, not system defaults.

Common Pitfalls

  • Assuming Claude's shell is the same as your terminal. It isn't. Your terminal is interactive; Claude's shell is not. Always verify with which and echo $PATH from within a Claude-executed command.
  • Using ~ in PATH strings. Some non-interactive shells don't expand ~. Use the full absolute path (/Users/you/.nvm/...) instead of ~/.nvm/....
  • Forgetting that nvm is a shell function, not a binary. You can't run nvm use 20 in Claude's shell because nvm is loaded as a shell function in .zshrc, which Claude's shell doesn't source. Use the absolute path to the Node binary directly.
  • Putting the wrong PATH first. If you prepend /usr/bin before your nvm path, the system Node shadows your nvm Node. Order matters — list your custom paths first.
  • Only fixing Node and forgetting other tools. If you use rg, jq, gh, or tree (all common Homebrew installs), they'll hit the same 127 error. Add /opt/homebrew/bin to the PATH fix, not just the nvm directory.

Prevention Checklist

  • Create a project .env file with the full PATH your tools require, using absolute paths (no ~).
  • Include all relevant tool directories: nvm node path, Homebrew bin, pyenv shims, Go bin, etc.
  • At the start of a session, ask Claude to run echo $PATH && which node && which python3 to verify the environment is correct.
  • If you switch Node versions via nvm mid-project, update the .env PATH to match.
  • Document the expected tool paths in your project README so Claude (and teammates) can reference them.
  • Test the fix by asking Claude to run node --version and confirming it reports the version you expect, not a system default.