Try free

Last updated 13 October 2026

Fix Claude Code nvm command not found

The shell context inside Claude Code sessions

When you launch a session with the command "claude", the agent executes commands using its Bash tool. This tool does not always inherit the full interactive environment you see in your standard terminal window. If your Node.js version manager relies on shell startup scripts like .bashrc or .zshrc to modify the PATH variable, the agent might lack those modifications. This leads to errors where the agent claims it cannot find node or nvm despite them being available to you manually.

The Bash tool typically runs in a mode that may skip certain initialization files depending on your operating system and shell configuration. You can verify this by asking the agent to run a command that prints the current PATH. If the output does not include the directories where nvm stores its binaries, the agent will fail to execute any scripts that depend on a specific Node.js version. Understanding this separation between your interactive shell and the agent execution environment is the first step to a fix.

Identifying the path mismatch

To diagnose the issue, you should use the Bash tool to inspect the environment from the perspective of the agent. Run a prompt asking the agent to show its current environment variables and the location of the node binary. If the agent returns an empty result for the node path or shows a system default version instead of your nvm version, you have confirmed a path mismatch. This often happens because nvm is a shell function rather than a standalone executable file, and it must be sourced before it can be used.

The agent relies on the Bash tool for almost all file system and build operations. When the agent tries to run an install command or a build script, it spawns a new process. If that process does not have the nvm initialization logic, the nvm command will not exist in that context. You can see this behavior clearly if you try to run nvm use inside a session and receive a command not found error even though you just used it in the terminal before starting the agent.

Project instructions in CLAUDE.md

One effective way to resolve path issues is to use the CLAUDE.md file in your project root. This file holds project instructions that the agent reads at the start of every session. You can explicitly tell the agent where your Node.js binaries are located or provide a specific command it should run before executing any build scripts. By adding these instructions to CLAUDE.md, you ensure that every time the agent uses the Bash tool, it follows the correct procedure to locate your tools.

In your CLAUDE.md, add a section that describes the environment setup. You might instruct the agent to always use a specific absolute path for the node and npm commands. For example, you can tell the agent that the project requires a specific version of Node.js located in your nvm folder. This prevents the agent from guessing which version to use or failing when it cannot find the nvm function. Since the agent reads this file before it begins working, it will incorporate these constraints into its planning and tool use.

Global configuration for all projects

If you find that every project you work on has the same nvm path issue, you should use the global CLAUDE.md file located at ~/.claude/CLAUDE.md. Instructions placed here apply to every session you start on your machine. This is the best place to define your environment variables if your nvm setup is consistent across your entire development environment. You can write a rule that tells the agent to always source the nvm initialization script before running any shell commands.

When you use the ~/.claude/CLAUDE.md file, the agent gains a persistent understanding of your local machine configuration. You can tell it that your shell is configured in a specific way and that it should check for the existence of certain paths. This global context reduces the need to repeat setup instructions in every repository. It also ensures that even when you use "claude --continue" to jump back into a project, the agent remembers the correct environment settings.

Using hook events for environment setup

Claude Code supports hook events that trigger at specific points in a session. You can use the SessionStart hook or the PreToolUse hook to run setup logic. While you cannot directly modify the shell environment of the parent process from within the session, you can use these hooks to alert yourself or the agent if the environment is not configured correctly. These hooks are defined in your settings.json file and provide a way to automate checks every time you start a new task.

For more complex setups, you might use a hook to verify that the current node version matches your project requirements. If you work on multiple projects with different Node.js versions, managing this manually can be tedious. This is where adhdTerminal is useful. It runs many Claude Code sessions side by side, each as a tile on a wall. You can see at a glance whether a session is working or waiting for you, making it easier to manage several different environment configurations simultaneously.

Modifying the shell configuration for non-interactive use

A more permanent fix involves ensuring your shell configuration files load nvm even in non-interactive sessions. Most developers put their nvm initialization in a block that only runs for interactive shells. You can move the nvm startup lines in your .zshrc or .bashrc file so they appear before the check for an interactive shell. This makes nvm available to any process that starts a shell, including the Bash tool used by the agent.

Be careful when modifying these files, as loading too many tools in non-interactive shells can slow down script execution. However, for a development machine, the overhead of loading nvm is usually acceptable. Once you make this change, the agent will be able to find the node and npm binaries because they will be correctly added to the PATH every time the agent invokes its Bash tool. You can verify this by running the "claude doctor" command to see if the environment looks correct.

Hardcoded paths as a fallback

If you prefer not to modify your shell configuration, you can instruct the agent to use absolute paths for all commands. Use the Edit tool to modify your CLAUDE.md or .claude/settings.json to specify these paths. For instance, you can find the actual location of the node binary by running "which node" in your interactive terminal and then tell the agent to use that exact string instead of just "node". This bypasses the need for the PATH variable to be set correctly for the nvm function.

This approach is very reliable because it does not depend on shell initialization logic. The agent will simply call the binary directly from its location on the disk. This is particularly helpful when working with build systems that have their own complex environment requirements. By being explicit about the location of your tools, you remove the ambiguity that leads to the command not found error. You can also use this method to point the agent to specific versions of other tools like yarn or pnpm.

Managing multiple environments efficiently

When you have many projects that each require a different version of Node.js, the overhead of switching versions can break your flow. If you use adhdTerminal, you can keep a dedicated tile open for each project you are currently working on. Since tiles reopen in the same place and resume the same session after a restart, you do not have to reconfigure your environment every time you switch tasks. The free iPhone app can even mirror the wall and let you answer a prompt or send the next task while you are away from your desk.

Using side-by-side tiles allows you to compare how different projects handle their nvm setup. You might have one project that uses a CLAUDE.md file to set the path and another that relies on a global shell configuration. By seeing these sessions as tiles on a wall, you can quickly identify if a path issue is specific to one repository or a broader problem with your machine. This visual organization helps keep your development environment stable while the agent handles the coding tasks.

Final verification of the fix

After you have applied one of these fixes, you should verify it within a session. Use the "claude --continue" command to enter your most recent session and ask the agent to run a simple node command, such as checking the version. If the agent successfully returns the version number without an error, your configuration is working. You should also try running a full build or install command to ensure that all sub-processes can also find the necessary binaries.

If the agent still struggles, use the /doctor command to check the health of your installation. This command can sometimes identify issues with how the agent interacts with your system tools. Remember that the agent respects your .gitignore file, so ensure that any environment files you want it to see are not being ignored. With the right path configuration, the agent becomes a much more powerful tool, capable of handling complex build and test cycles without manual intervention.

Questions people ask

Can I use nvm alias default to fix this?

Setting a default alias in nvm helps if the agent falls back to a system node, but it does not fix the issue where the nvm command itself is missing. The agent needs the shell to source the nvm script to recognize the command. It is better to provide the absolute path to the node binary in your project instructions.

Why does which node work in my terminal but not for the agent?

Your interactive terminal loads configuration files like .zshrc that the agent's non-interactive Bash tool might skip. The agent runs in a separate process that does not inherit your shell functions or aliases. You must ensure the environment is initialized for every shell execution the agent performs.

Does the /clear command reset my path settings?

The /clear command resets the conversation history but does not change your CLAUDE.md or shell configuration. If your path issues are fixed in those files, the agent will still have the correct environment after you clear the session. It is a good way to test if a configuration change works starting from a fresh state.

Read next

More on when it goes wrong·All posts