Why npm Works Over SSH but Fails in Automated Deployments

Last updated on August 21st, 2026 at 01:06 pm

The main lesson: when Node.js is installed through NVM, an automated deployment may not know where node and npm are—even though both commands work in a normal SSH session.

What I learned

Many deployment tools run commands in a non-interactive shell. That shell often does not load the same startup files as an interactive SSH session.

NVM is a shell-based Node.js version manager. If its initialization script is not loaded, the selected Node.js version is not added to PATH. The deployment then reports npm: command not found.

How to fix it

1. Run the deployment as the same account that owns the NVM installation.
2. Set the NVM directory explicitly.
3. Load the NVM initialization script before using Node.js.
4. Select the required Node.js version.
5. Verify the commands before starting the build.

set -e

export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"

if [ ! -s "$NVM_DIR/nvm.sh" ]; then
    echo "NVM initialization script not found"
    exit 1
fi

. "$NVM_DIR/nvm.sh"
nvm use default

node --version
npm --version
npm ci
npm run build

If the project includes an .nvmrc file, use nvm use so the deployment selects the version declared by the project.

How to diagnose the failure

Add these checks near the start of the remote deployment script:

whoami
printf '%s\n' "$HOME"
command -v node
command -v npm

If the manual SSH session and the deployment use different accounts, they may have different NVM installations and startup files.

Common mistakes

• Cause: NVM is configured only in an interactive shell file. Fix: load nvm.sh inside the deployment script.
• Cause: the deployment connects as a different account. Fix: confirm whoami and the home directory.
• Cause: a warning appears just before the failure. Fix: identify the actual failing command; status code 127 usually means “command not found.”
• Cause: cleanup output makes a failed deployment look successful. Fix: preserve the build’s non-zero exit status and fail the job.

Conclusion

When a command works over SSH but fails in automation, compare the shell environment before reinstalling anything. The next action is to load NVM explicitly and verify node and npm before the build.

Tags:

• automation
• error
• Node.js
• NPM