Fixing "Bash: node: command not found" when running a shell script

The "Bash: node: command not found" error occurs because the shell cannot locate the Node.js executable in your system's PATH environment variable. This typically happens when Node is installed via a version manager like nvm, or when the installation directory was not added to your profile configuration files such as .bashrc or .profile.

Understanding the Root Cause

When you execute a command in Bash, the shell searches through directories listed in the PATH environment variable to find the corresponding executable file. If Node.js is installed but its binary location (usually /usr/local/bin/node, ~/.nvm/versions/node/vX.X.X/bin/node, or similar) is missing from this list, Bash throws the command not found error. This issue is distinct from syntax errors or missing dependencies; it is purely a path resolution problem. Common scenarios include installing Node.js globally without updating shell configurations, using a package manager that isolates binaries, or running scripts in an environment where environment variables are not inherited correctly.

Verifying Node.js Installation

Before modifying paths, confirm that Node.js is actually installed on your system. Open your terminal and run the following command:

which node

If this returns a path, note it down. If it returns nothing, Node.js might not be installed, or it is installed in a non-standard location. You can also check the version to ensure it is functional:

node --version

If this command fails with the same command not found error, proceed to the next step to manually locate the binary. On Linux and macOS, you can search for the binary using:

find / -name "node" -type f 2>/dev/null

This command scans the entire filesystem for a file named node. Be aware that this may take some time depending on your disk size. Once you identify the correct path, add it to your PATH. For Windows users, ensure that the Node.js installation directory is included in the System Environment Variables under Path.

Updating Your Shell Configuration

The most common fix involves editing your shell's initialization file. For Bash users, this is typically ~/.bashrc or ~/.bash_profile. For Zsh users, it is ~/.zshrc. Open the relevant file in a text editor:

nano ~/.bashrc

Add the following line at the end of the file, replacing /path/to/node with the actual path you found earlier:

export PATH="/path/to/node/bin:$PATH"

If you are using a version manager like nvm, you likely already have initialization code in your config file. Ensure that the nvm setup block is present and not commented out. After saving the file, reload your shell configuration by running:

source ~/.bashrc

Or simply close and reopen your terminal window. Verify the fix by running node --version again. If you frequently switch between projects or environments, consider adding conditional logic to your config file to manage multiple Node versions efficiently. For more insights on optimizing your shell environment, see How to Improve Bash Performance and Secure Passwords.

Using Version Managers

To prevent path issues entirely, use a Node version manager like nvm (Node Version Manager), n, or fnm. These tools handle PATH updates automatically. Install nvm by following the official installation script from their GitHub repository. Once installed, install a specific version of Node.js:

nvm install 18

Then set it as the default:

nvm alias default 18

nvm will automatically update your PATH whenever you switch versions or open a new terminal session. This approach eliminates manual path configuration and reduces the likelihood of encountering command not found errors. It is particularly useful for developers working on multiple projects with different Node.js requirements.

Debugging Script Execution Contexts

Sometimes the error appears only when running a shell script rather than interactively in the terminal. This happens because scripts often run in a non-interactive, non-login shell context, which may not source ~/.bashrc or ~/.profile. To fix this, explicitly set the PATH at the beginning of your script:

#!/bin/bash
export PATH="/usr/local/bin:/usr/bin:/bin:$PATH"
# Your script commands here
node app.js

Alternatively, use absolute paths to the Node executable within your script if the PATH modification is not feasible. This ensures that the script finds Node regardless of the calling environment. If you need to write debug data to files during execution, refer to How to Write Debug Data to a Root Owned File in Bash for best practices on handling permissions and output redirection.

Checking for Symlink Issues

In some cases, the node binary exists but is broken due to a missing symlink. Check if the symlink points to a valid file:

ls -l $(which node)

If the target is missing, recreate the symlink manually or reinstall Node.js. On macOS with Homebrew, you can relink packages:

brew link node

On Linux, ensure that your user has read and execute permissions for the Node binary directory. Incorrect permissions can sometimes mimic command not found errors depending on the shell's security settings.

Frequently Asked Questions

Why does 'node' work in the terminal but not in my script?

Scripts often run in a minimal environment that does not load your interactive shell configuration files like .bashrc. To resolve this, define the PATH explicitly at the top of your script or use absolute paths to the Node executable.

How do I find where Node.js is installed?

Use the which node command in your terminal. If it returns nothing, use find / -name "node" -type f to search the entire filesystem, keeping in mind that this may require administrative privileges and time.

Can I use NVM to fix this error permanently?

Yes, using nvm is the recommended long-term solution. It automatically manages your PATH and allows you to switch between Node versions seamlessly without manual configuration errors.

What should I do if I get permission denied after fixing the path?

Ensure that the Node binary has execute permissions. You can change permissions using chmod +x /path/to/node. Additionally, verify that your user account has read access to the directory containing the Node executable.

Does changing PATH affect other applications?

Modifying your PATH generally affects all applications launched from your shell. However, adding Node.js to the front or back of the PATH usually does not conflict with other tools unless you have conflicting executables with the same name, which is rare for node.