Invalidate Cache

In this lesson we show how to invalidate a Jenkins dependency cache automatically whenever project dependencies change — specifically when package-lock.json (or yarn.lock) is updated. This ensures fast builds when dependencies are unchanged, and safe cache refreshes when they are not.

A blue-to-teal gradient slide with subtle diamond shapes and centered white text that reads "Invalidate Caching." A small "© Copyright KodeKloud" appears in the bottom-left.

The Job Cacher plugin supports a cache-validity mechanism using a cache-validity deciding file (for example: package-lock.json). When that file changes, the plugin computes a new hash and decides whether an existing cache is still valid. Below is the Jenkins pipeline snippet used to cache node_modules and to make package-lock.json the cache-validity file.

options { timestamps() }
steps {
  cache(maxCacheSize: 550, caches: [
    arbitraryFileCache(
      cacheName: 'npm-dependency-cache',
      cacheValidityDecidingFile: 'package-lock.json',
      includes: '**/*',
      path: 'node_modules')
  ]) {
    sh 'node -v'
    sh 'npm install --no-audit'
    stash(includes: 'node_modules/', name: 'solar-system-node-modules')
  }
}

Demonstration — add a dependency locally in the repository:

root@jenkins-controller-1 in solar-system on ⬢ feature/advanced-demo via ⬢ v20.16.0 on ☁ (us-east-2)
➜ npm install localtunnel

npm reports the new installation:

added 7 packages, and audited 366 packages in 2s

45 packages are looking for funding
  run `npm fund` for details

10 vulnerabilities (1 low, 4 moderate, 5 high)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

Installing the dependency updates both package.json and package-lock.json. When you commit and push these changes the pipeline triggers, and the Job Cacher plugin computes a hash of package-lock.json and compares it with the hash associated with the stored cache archive. Representative pipeline logs for the two outcomes:

Cache is up-to-date and is restored:

[Cache for node_modules (npm-dependency-cache) with id 3ec03583f8eaec275cb2183db769ff47] Searching cache in job specific caches...
[Cache for node_modules (npm-dependency-cache) with id 3ec03583f8eaec275cb2183db769ff47] got hash a47b9ef02dbc79db72ab6385105e0142 for cacheValidityDecidingFile(s) - actual file(s): /var/lib/jenkins/workspace/solar-system_feature_advanced-demo/package-lock.json
[Cache for node_modules (npm-dependency-cache) with id 3ec03583f8eaec275cb2183db769ff47] Found cache in job specific caches
[Cache for node_modules (npm-dependency-cache) with id 3ec03583f8eaec275cb2183db769ff47] Restoring cache...
[Cache for node_modules (npm-dependency-cache) with id 3ec03583f8eaec275cb2183db769ff47] Cache restored in 771ms
+ node -v
v22.6.0
+ npm install --no-audit
up to date in 1s

44 packages are looking for funding
  run `npm fund` for details

Stashed 4993 file(s)
[Cache for node_modules (npm-dependency-cache) ...] Skip cache creation as the cache is up-to-date

package-lock.json changed — cache is outdated and is recreated:

[Cache for node_modules (npm-dependency-cache) with id 3ec03583f8eaec275cb2183db769ff47] Searching cache in job specific caches...
[Cache for node_modules (npm-dependency-cache) with id 3ec03583f8eaec275cb2183db769ff47] got hash 5a15d94c8bab08a6882fddf4b8ef16c2 for cacheValidityDecidingFile(s) - actual file(s): /var/lib/jenkins/workspace/solar-system_feature_advanced-demo/package-lock.json
[Cache for node_modules (npm-dependency-cache) ...] cacheValidityDecidingFile configured, but previous hash does not match - cache outdated
[Cache for node_modules (npm-dependency-cache) ...] Skip restoring cache as no up-to-date cache exists
+ node -v
v22.6.0
+ npm install --no-audit
added 7 packages in 2s

45 packages are looking for funding
  run `npm fund` for details

Stashed 5131 file(s)
[Cache for node_modules (npm-dependency-cache) ...] Creating cache...
[Cache for node_modules (npm-dependency-cache) ...] Cache created in 2179ms

How it works (step-by-step)

The plugin computes a hash of the configured cache-validity file(s) (in this example: package-lock.json) in the current workspace.
It compares that hash with the hash associated with the existing cache for this job.
- If the hashes match, the plugin restores the cache and the build step finishes quickly (for example: npm install reports “up to date”).
- If the hashes differ, the plugin treats the cache as outdated, skips restoration, runs the install to produce up-to-date node_modules, then creates a new cache using the new hash.
Subsequent builds with the same package-lock.json content will restore the newly created cache until the lockfile changes again.

Quick reference table

Condition	Plugin action	Typical result
`package-lock.json` hash matches stored cache	Restore cache	`npm install` is fast — “up to date”
`package-lock.json` hash differs	Skip restore, run install, create new cache	Fresh `node_modules` created and cached

Use cacheValidityDecidingFile (for example, package-lock.json or yarn.lock) so the Job Cacher invalidates dependency caches whenever the lockfile changes. This maintains build speed for unchanged dependencies while preventing stale or incompatible modules from being reused.

Links and references

Job Cacher plugin (Jenkins) — check the plugin documentation in your Jenkins instance or the plugin site for configuration details.
Jenkins pipeline documentation: https://www.jenkins.io/doc/book/pipeline/
npm lockfile formats and behavior: https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json

That’s all for now.

Shared Libraries in Jenkins

Agents and Nodes in Jenkins

Pipeline Enhancement and Caching

Pipeline Structure and Scripted vs Declarative

Jenkins Administration and Monitoring

Backup and Configuration Management

Introduction

Watch Video

Practice Lab