npm — ERR! code EINTEGRITY from a Corrupted Cache

Resolve npm ERR! code EINTEGRITY integrity check failures by verifying the lockfile hash source, clearing the right cache slice, and pinning registry mirrors.

intermediatedebuggingnpmtooling

Symptoms

npm ERR! code EINTEGRITY with npm ERR! request to https://registry.npmjs.org/... failed, reason: integrity checksum failed
The failure names a specific tarball and expected sha512 value that does not match the fetched one
Installs fail on one machine or CI runner while colleagues and other runners succeed

Possible causes

A partially downloaded or corrupted tarball sits in the local npm cache and fails the sha512 comparison
A corporate proxy or registry mirror serves a different artifact than the lockfile recorded
The lockfile integrity field was hand-edited or generated by a different tool
A corrupted content-addressable cache entry after a disk-full event during a previous install

Diagnosis steps

Read the expected and actual digests

npm install 2>&1 | grep -A4 EINTEGRITY

Interpretation

The message pairs the expected sha512 from the lockfile with the computed one; a mismatch isolated to one machine points at the local cache, a mismatch everywhere points at the registry source.

Verify the artifact against the registry directly

curl -s https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz | openssl dgst -sha512

Interpretation

If the digest from the upstream registry matches the lockfile, the tarball is fine and the corruption is local; if it differs, the mirror is serving altered bytes.

Inspect and clean only the failing slice

npm cache verify && npm cache clean --force

Interpretation

cache verify reports corrupted entries; the clean rebuilds them. Cleaning the whole cache is heavy but guarantees no stale corrupted slice survives.

Root cause

npm compares the sha512 in the lockfile against the tarball it retrieves. A corrupted cache entry, an altered artifact from a mirror, or a modified integrity field makes the comparison fail, and npm refuses to install rather than proceed with bytes that do not match the recorded hash.

Fix

When the digest matches upstream, clear the local cache and reinstall. When the digest differs from upstream, fix the registry source: remove the mirror override, re-point DNS or proxy rules, and if the lockfile itself was edited, regenerate it from a trusted registry.

Risk note

Disabling integrity checking with a legacy config trades away the only tamper protection in the install path. Never ship that workaround.

Verify the fix

After the fix, run npm ci from scratch on the affected machine and confirm a clean install; repeat on a second runner to prove reproducibility.

Symptom walkthrough

The error is unusually helpful because it prints both digests:

npm ERR! code EINTEGRITY
npm ERR! sha512-integrity checksum failed when using sha512:
  wanted: sha512-ZX/...9fA
  found:   sha512-k4/...2eQ

Three parties can be at fault: the cache (returned corrupted bytes), the registry source (served different bytes), or the lockfile (records the wrong expectation). Decide which by fetching the tarball straight from the official registry and hashing it yourself. Matching the lockfile means local corruption; mismatching means your mirror altered the artifact.

Fix in practice

For local corruption, reset the cache and reinstall:

npm cache verify       # reports corrupted entries
npm cache clean --force
rm -rf node_modules package-lock.json.bak
npm ci

For a mirror problem, trace where the URL actually points:

npm config get registry
npm config delete registry   # or fix .npmrc to the intended mirror

Compare the .npmrc hierarchy too: project, user, and global configs each override the previous one, and a stale corporate mirror line often hides in the user-level file. If the lockfile integrity was edited by hand or a non-npm tool, regenerate it: delete package-lock.json, install once from a trusted registry, and commit the regenerated file.

Verification

On the previously failing machine, remove node_modules and run npm ci to force a full fetch. A completed install with zero integrity errors proves the cache is clean. Then verify the mechanism stayed intact: deliberately corrupt one cached tarball in a sandbox copy and confirm npm still fails with EINTEGRITY — the guard must remain armed, not bypassed. Finally repeat the full install on a second CI runner to demonstrate the fix reproduces rather than being machine luck.