Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Jenkins job cannot find npm or node

Errornpm: command not found

Short answer

Jenkins runs steps with the agent's own PATH, which usually has no Node.js. Install the NodeJS plugin, add a NodeJS installation under Manage Jenkins, Tools, and then enable it in the job: the build environment option for freestyle jobs, or the nodejs wrapper step in a pipeline.

  • Applies to Jenkins 2.x LTS, NodeJS plugin, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print what the build step sees. If npm is missing from the output, the job has no Node.js on its PATH.

    echo "$PATH"
    which node npm || echo "node and npm not on PATH"
  2. 2Match what you see, then jump to its fix

    1. 1The Tools page has no NodeJS section, or no installation named in the jobNo NodeJS installation is configured in JenkinsFix
    2. 2npm not found in a shell build step of a freestyle jobA freestyle job does not use the installationFix
    3. 3npm not found inside sh in a JenkinsfileA pipeline does not wrap its steps in the NodeJS toolFix

What does the error look like?

  • npm: command not found
  • node: command not found

Cause 1 of 3

No NodeJS installation is configured in Jenkins

1Check

Open the Tools page of Jenkins (JENKINS_URL/configureTools) and look for a NodeJS section. It only exists once the NodeJS plugin is installed.

echo "$JENKINS_URL"

2Fix

Install the NodeJS plugin, then add a NodeJS installation. You can let Jenkins install it from the nodejs.org mirror, and name it (for example node-22) so jobs can refer to it.

# Manage Jenkins -> Plugins -> install "NodeJS"
# Manage Jenkins -> Tools -> NodeJS installations -> Add NodeJS
#   Name: node-22   (Install automatically)

3Verify

The installation name appears in the job configuration, as in the next causes.

# job configuration lists node-22

Confirmed by plugins.jenkins.io

Did this fix it?

Cause 2 of 3

A freestyle job does not use the installation

1Check

The installation exists, but the job has not been told to add its bin folder to PATH.

# job configuration -> Build Environment

2Fix

In the Build Environment section, select the NodeJS installation. Jenkins then adds its bin folder to PATH for the shell steps.

# Build Environment -> select the NodeJS installation (node-22)
# Build step: Execute shell
npm ci
npm test

3Verify

Run the job and check that npm --version prints in the console log.

npm --version

Confirmed by plugins.jenkins.io

Did this fix it?

Cause 3 of 3

A pipeline does not wrap its steps in the NodeJS tool

1Check

The declarative tools directive supports only maven, jdk and gradle, so it cannot provide Node.js. The NodeJS plugin offers a nodejs wrapper step (declarative) and a tool step (scripted) instead.

grep -n -E "nodejs|tool " Jenkinsfile

2Fix

Wrap the steps in nodejs(...) using the name from the Tools page.

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        nodejs(nodeJSInstallationName: 'node-22') {
          sh 'npm ci && npm test'
        }
      }
    }
  }
}

3Verify

The console log shows npm output instead of command not found.

# Console output of the build

Confirmed by jenkins.io

Did this fix it?

How do I stop it coming back?

  • Keep one named NodeJS installation per major version and reference it by name in every job.
  • Pin the version in the installation so builds do not change when Node.js releases.
  • Check the agent label: a job that runs on a different agent needs the same tool available.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.