npm "Cannot read properties of null (reading 'matches')" - Fix the Cache Bug in CI

This internal npm error - a null dereference deep in npm’s code - is usually triggered by a corrupted or stale npm cache, not by your project. Clearing the cache almost always resolves it.

What this error means

npm install/npm ci crashes with an internal stack trace ending in "Cannot read properties of null (reading 'matches')". It often appears after a restored CI cache or an interrupted previous install.

npm output

npm error Cannot read properties of null (reading 'matches')
npm error A complete log of this run can be found in:
npm error     /home/runner/.npm/_logs/2026-...-debug-0.log

Common causes

A corrupted or stale npm cache

A partially written _cacache entry - often from a restored CI cache or a killed install - leaves npm’s metadata in a state its resolver does not expect, producing a null dereference.

An npm version with a known cache-handling bug

Some npm versions have bugs in this code path that surface against odd cache or lockfile states; updating npm can sidestep it.

How to fix it

Clean the cache and reinstall

Force-clear the npm cache and remove node_modules so the bad state is rebuilt.

Terminal

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Update npm and bust the cache key

Update npm (npm install -g npm@latest) to move off a buggy version.
Change the CI cache key so a fresh ~/.npm is built.
Re-run after cleaning - the error rarely repeats on a clean cache.

How to prevent it

Bust the npm cache key when internal npm errors appear.
Keep npm reasonably current in CI images.
Avoid restoring a half-written cache from a cancelled run.