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 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.logCommon 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.
npm cache clean --force
rm -rf node_modules package-lock.json
npm installUpdate 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
~/.npmis 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.