Chapter 21: Jenkins Pipeline and Jenkinsfile

21.7 Agent tools: Node must exist

By Ravindra Bagale · Last updated: 25 October 2026

Why: the problem

A common first error in Jenkins is npm: not found. The Jenkinsfile is fine. The agent simply has no Node. Jenkins does not install tools by magic. Think of a new Infosys project. The team has three Node versions across apps: 18, 20 and 22. If every agent has only one Node, some builds break. There are three good ways to give a build the right tool. One, install it on the agent and give the agent a label. Two, use the Jenkins tools block, which downloads Node into the agent on first use. Three, run the stage inside a Docker image like node:20, so the tool comes with the image. In this lesson you will try all three, print the version each time, and learn when to pick which.

What we will build

You will install the NodeJS plugin and set up two Node versions in Global Tool Configuration. You will use the tools block. Then you will run a stage inside a node:20 Docker container. Finally you will build on two Node versions and compare.

What: every term in plain English

• Tool installation — A tool Jenkins can download and put on an agent, like Node, Maven or JDK.
• tools block — Declarative block that adds a configured tool to the PATH.
• NodeJS plugin — Plugin that adds Node.js as a Jenkins tool.
• PATH — The list of folders where the shell looks for commands.
• Docker agent — agent { docker { image ... } }. The stage runs inside a container.
• Docker Pipeline plugin — Plugin that gives the docker agent.
• Label — A tag on an agent that has a tool, like node20.
• nvm — Node Version Manager. Used on agents to install many Node versions.

How: step by step

1. Install the plugin

   Manage Jenkins > Plugins > NodeJS, Docker Pipeline
   

   What it does: Adds Node tools and docker agents.

   Output

   Success
   

2. Add Node 20

   Manage Jenkins > Tools > NodeJS installations > Add > Name: node20 > Install automatically > Version 20.15.1
   

   What it does: Jenkins downloads Node on first use.

   Output

   Saved
   

3. Add Node 18

   Add > Name: node18 > Version 18.20.4
   

   What it does: Second version for old apps.

   Output

   Saved
   

4. Use tools

   tools { nodejs "node20" }
   

   What it does: Adds node20 to PATH for the pipeline.

   Output

   Unpacking ... node-v20.15.1-linux-x64.tar.gz
   

5. Check Docker on the agent

   docker version --format "{{.Server.Version}}"
   

   What it does: The docker agent needs Docker on the agent machine.

   Output

   26.1.4
   

6. Run in a container

   agent { docker { image 'node:20-alpine' } }
   

   What it does: The stage runs inside node:20.

   Output

   Pulling node:20-alpine
   

Example 1: The tools block

Stack. NodeJS plugin

Goal. The tools block.

Jenkinsfile

pipeline {
  agent any
  tools { nodejs 'node20' }
  stages {
    stage('Versions') {
      steps {
        sh 'which node'
        sh 'node --version && npm --version'
      }
    }
    stage('Test') { steps { sh 'npm ci && npm test' } }
  }
}

What each line does

• tools { nodejs 'node20' } — Name must match the name in Tools.
• which node — Shows where Node came from.
• First run — Downloads Node once, then reuses it.

Green output

Unpacking https://nodejs.org/dist/v20.15.1/node-v20.15.1-linux-x64.tar.gz to /var/jenkins_home/tools/jenkins.plugins.nodejs.tools.NodeJSInstallation/node20
+ which node
/var/jenkins_home/tools/jenkins.plugins.nodejs.tools.NodeJSInstallation/node20/bin/node
+ node --version
v20.15.1
10.7.0
Tests: 2 passed, 2 total
Finished: SUCCESS

Expected result. Node came from the Jenkins tool folder, not the system.

Example 2: Docker agent with node:20

Stack. Docker Pipeline plugin

Goal. Docker agent with node:20.

Jenkinsfile

pipeline {
  agent {
    docker {
      image 'node:20-alpine'
      args '-v npm-cache:/home/node/.npm'
      reuseNode false
    }
  }
  environment { HOME = "${env.WORKSPACE}" }
  stages {
    stage('Versions') { steps { sh 'node --version && cat /etc/os-release | head -2' } }
    stage('Test')     { steps { sh 'npm ci && npm test' } }
  }
}

What each line does

• image 'node:20-alpine' — A small official Node image.
• args '-v npm-cache:...' — Keeps the npm cache in a volume between builds.
• HOME = WORKSPACE — npm needs a writable home inside the container.
• cat /etc/os-release — Proves the stage ran in Alpine.

Green output

Pulling node:20-alpine
$ docker run -t -d -u 1000:1000 -v npm-cache:/home/node/.npm -w /var/jenkins_home/workspace/badge-scm ... node:20-alpine cat
+ node --version
v20.15.1
NAME="Alpine Linux"
ID=alpine
Tests: 2 passed, 2 total
$ docker stop --time=1 4c1d...
Finished: SUCCESS

Expected result. The agent needs only Docker. Node comes with the image.

Example 3: Test on Node 18 and 20 in two stages

Stack. Docker agents

Goal. Test on Node 18 and 20 in two stages.

Jenkinsfile

pipeline {
  agent none
  stages {
    stage('Node 18') {
      agent { docker { image 'node:18-alpine' } }
      environment { HOME = "${env.WORKSPACE}" }
      steps { sh 'node --version && npm ci && npm test' }
    }
    stage('Node 20') {
      agent { docker { image 'node:20-alpine' } }
      environment { HOME = "${env.WORKSPACE}" }
      steps { sh 'node --version && npm ci && npm test' }
    }
  }
}

What each line does

• agent none — Each stage picks its own agent.
• Two images — Same tests, two Node versions.
• Parallel later — Lesson 21.14 runs these at the same time.

Green output

[Pipeline] stage (Node 18)
v18.20.4
Tests: 2 passed, 2 total
[Pipeline] stage (Node 20)
v20.15.1
Tests: 2 passed, 2 total
Finished: SUCCESS

Expected result. The app works on both versions. Safe to upgrade.

Example 4: A label based agent with nvm for many versions

Stack. nvm on a permanent agent

Goal. A label based agent with nvm for many versions.

agent setup (run once on the agent)

# download install.sh from the official nvm project page first
less install.sh
bash install.sh
. ~/.nvm/nvm.sh
nvm install 18 && nvm install 20 && nvm install 22
nvm ls

Jenkinsfile

pipeline {
  agent { label 'node-multi' }
  stages {
    stage('Node 22') {
      steps { sh 'bash -lc ". ~/.nvm/nvm.sh && nvm use 22 && node --version && npm ci && npm test"' }
    }
  }
}

What each line does

• less install.sh — Read a script before you run it.
• nvm install — Installs each Node version in the jenkins user home.
• label 'node-multi' — Only agents with nvm get this label.
• bash -lc — Login shell, so nvm loads.

Green output

       v18.20.4
       v20.15.1
->     v22.4.1
...
Now using node v22.4.1 (npm v10.8.1)
v22.4.1
Tests: 2 passed, 2 total
Finished: SUCCESS

Expected result. This works for long lived agents. Docker images are still cleaner for most teams.

Verify: did it work?

1. List tools on the controller

   docker exec jenkins ls /var/jenkins_home/tools/jenkins.plugins.nodejs.tools.NodeJSInstallation
   

   What it does: Shows downloaded Node versions.

   Output

   node18
   node20
   

2. Check images on the agent

   docker images node
   

   What it does: Shows cached Node images.

   Output

   node 20-alpine 1.2e+08
   node 18-alpine 1.3e+08
   

When it is red 1

sh: 1: npm: not found

Cause. No Node on the agent and no tools or docker block.

Fix, step by step

1. Add tools nodejs or a docker agent.
2. Or use a node20 labelled agent.

When it is red 2

Tool type nodejs does not have an install of node-20 configured

Cause. Name in tools does not match Tools page.

Fix, step by step

1. Copy the exact name.

When it is red 3

docker: not found / Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Cause. The agent has no Docker or the jenkins user cannot use it.

Fix, step by step

1. Install Docker on the agent.
2. Add jenkins to the docker group and restart the agent.

When it is red 4

npm ERR! code EACCES ... mkdir '/.npm'

Cause. npm has no writable home in the container.

Fix, step by step

1. Set HOME to WORKSPACE.

Cleanup

1. Remove old images

   docker image prune -f
   

   What it does: Frees disk on the agent.

   Output

   Total reclaimed space: 412MB
   

2. Remove npm cache volume

   docker volume rm npm-cache
   

   What it does: Clears the lab cache.

   Output

   npm-cache
   

Practice tasks

Homework: try at home

Recap

• Jenkins does not bring tools by itself.
• Use labels, tools or Docker images.
• Tool names must match exactly.
• Docker agents keep agents clean.
• Print versions in every build.

FAQ

Which way do companies use?

Mostly Docker or Kubernetes pod agents, so each build has its own tools.

Is the tools block bad?

No, it is fine for small setups.

Can I pin an exact image?

Yes, use a digest like node:20-alpine@sha256:... for repeatable builds.

Does the docker agent work on Windows agents?

Only with Linux containers support. Use Linux agents for Docker builds.

Where is the npm cache?

In HOME/.npm. Use a volume to keep it.

Interview questions

1. Build says npm not found. What do you do?

   Give the build Node via a labelled agent, tools block, or docker agent, and print the version.

2. tools block vs docker agent?

   tools downloads into the agent; docker runs the stage in an image with the tool. Docker is cleaner and repeatable.

3. How do you test on two versions?

   Separate stages or a matrix with different images.

4. Why can a docker agent fail with permission denied on docker.sock?

   The jenkins user is not in the docker group.

5. How do you make builds repeatable?

   Pin tool versions and image digests.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards