🚨 Security Error Guide: npm EINTEGRITY 'sha512 integrity checksum failed'

Overview

npm uses Subresource Integrity (SRI) hashes to guarantee that the package tarball it downloads is byte-for-byte the one recorded in your package-lock.json. Every resolved dependency carries an integrity field (a sha512-... hash). Before installing, npm hashes the downloaded tarball and compares it; if they differ, it aborts with EINTEGRITY. This is a supply-chain control: a mismatch can mean a package was altered in transit, a registry served different bytes, or a proxy/cache is corrupt. It also fires benignly when a lockfile hash is stale or the local cache is damaged — so you diagnose, you do not blindly bypass.

The literal error:

npm error code EINTEGRITY
npm error sha512-4Xz... integrity checksum failed when using sha512:
wanted sha512-4Xz...Ug== but got sha512-9Kp...bA==.
(65432 bytes)

The yarn/pnpm equivalents carry the same meaning:

error https://registry.npmjs.org/left-pad/-/left-pad-1.3.0.tgz: Integrity check failed for "left-pad" (computed integrity doesn't match our records, got "sha512-9Kp...bA==")

The two hashes are the whole story: wanted is what your lockfile trusts, got is what was actually downloaded. When they disagree, npm refuses rather than install unverified bytes.

Symptoms

• npm ci or npm install fails with code EINTEGRITY and a wanted ... but got ... pair.
• CI fails on integrity while a developer machine installs fine (or vice versa), pointing at a cache or registry difference.
• The failure started after switching registries, adding a proxy/mirror, or bumping a package version.
• Repeated installs fail identically (deterministic) or intermittently (transport/proxy corruption).

npm ci 2>&1 | grep -A2 EINTEGRITY

npm error code EINTEGRITY
npm error sha512-... integrity checksum failed when using sha512: wanted sha512-... but got sha512-...

Common Root Causes

1. Stale or hand-edited lockfile hash

package-lock.json records an integrity that no longer matches the version being served (a bad merge, a manual edit, or a republished version). The lockfile’s expectation is simply wrong.

grep -A2 '"left-pad"' package-lock.json | grep integrity

"integrity": "sha512-4Xz...Ug=="

2. Corrupt local npm cache

A partially written or damaged cache entry produces a tarball whose hash doesn’t match, even though the registry copy is fine.

npm cache verify

Content verified: 5123 (412345678 bytes)
Corrupted content removed: 2

3. A proxy, mirror, or CDN serving different bytes

A caching proxy (Nexus, Artifactory, Verdaccio) or a transparent corporate proxy returns a re-compressed or altered tarball, changing the hash.

npm config get registry
curl -sI "$(npm config get registry)left-pad/-/left-pad-1.3.0.tgz" | grep -i 'content-length\|via\|x-cache'

4. Registry switch with mismatched integrity

The lockfile’s integrity was generated against one registry (e.g., npmjs) but installs now run against a mirror that stores a differently-hashed artifact.

5. Republished package version (rare, and a real supply-chain signal)

An upstream version was unpublished and republished with different content, so the trusted hash no longer matches. Treat this as suspicious until confirmed with the maintainer/advisories.

Diagnostic Workflow

Step 1: Read both hashes and identify the package

npm ci 2>&1 | grep -E 'wanted|got|integrity checksum'

Note which package/version and the wanted vs got hashes — everything else hangs off this.

Step 2: Rule out the local cache first (cheapest fix)

npm cache verify
npm cache clean --force
npm ci

If a clean cache resolves it, the download was locally corrupt — no lockfile change needed.

Step 3: Check which registry/proxy is serving the package

npm config get registry
cat .npmrc 2>/dev/null; cat ~/.npmrc 2>/dev/null | grep -i registry

If a mirror is in play, fetch the tarball directly and compare its hash to the lockfile:

TGZ=$(npm view left-pad@1.3.0 dist.tarball)
curl -sL "$TGZ" -o /tmp/p.tgz
cat /tmp/p.tgz | openssl dgst -sha512 -binary | openssl base64 -A | sed 's/^/sha512-/'

Compare that to both the wanted lockfile value and what your proxy returns.

Step 4: Compare against the public registry’s recorded integrity

npm view left-pad@1.3.0 dist.integrity

If the public registry’s integrity matches your lockfile but the proxy’s bytes don’t, the proxy/mirror is the culprit — fix or bypass the proxy, don’t edit the lockfile.

Step 5: Refresh the lockfile only if the recorded hash is genuinely stale

When the public registry’s current integrity differs from your stale lockfile (e.g., after a legitimate version change), regenerate the entry:

rm -rf node_modules
npm install --package-lock-only
git diff package-lock.json   # review the integrity change before committing

Example Root Cause Analysis

CI starts failing every build with EINTEGRITY on a single dependency, while developers on the public npm registry install cleanly:

npm ci 2>&1 | grep -E 'wanted|got'

wanted sha512-4Xz...Ug== but got sha512-9Kp...bA==

The difference between CI and laptops is the registry: CI is pinned to an internal Artifactory mirror. Fetching the tarball from both sources and hashing them shows the mirror returns different bytes than npmjs:

# public registry integrity
npm view left-pad@1.3.0 dist.integrity
# -> sha512-4Xz...Ug==   (matches the lockfile "wanted")

# mirror-served tarball
curl -sL "$(npm config get registry)left-pad/-/left-pad-1.3.0.tgz" | openssl dgst -sha512 -binary | openssl base64 -A
# -> 9Kp...bA==   (the "got" value)

The public registry’s integrity matches the lockfile; the mirror is serving a re-compressed tarball with a different hash. The lockfile and the package are fine — the proxy corrupted (re-gzipped) the artifact. Integrity checking correctly caught it.

Fix: repair the mirror (purge and re-cache the artifact so it stores the upstream bytes), then re-run npm ci:

# after purging left-pad@1.3.0 from the mirror's cache so it refetches upstream
npm ci

added 214 packages in 6s

No lockfile edit and no integrity bypass — the fix was in the proxy, exactly where the mismatch originated.

Prevention Best Practices

• Use npm ci (not npm install) in CI so the lockfile is authoritative and integrity is always enforced.
• Never “fix” EINTEGRITY by deleting the lockfile, editing the hash by hand, or setting anything that disables integrity — that discards the supply-chain guarantee.
• Configure caching proxies to store and serve byte-identical upstream tarballs (avoid re-compression); verify with a hash comparison after any proxy upgrade.
• Commit package-lock.json and review integrity changes in PRs; an unexpected hash change on an unchanged version is worth investigating.
• Enable and heed npm audit signatures where the registry supports signed provenance, adding a second layer beyond SRI hashes.
• If a republished version is the cause, confirm via the maintainer and security advisories before trusting the new hash — a silent content change is a real supply-chain signal.

Quick Command Reference

# See the failing package and both hashes
npm ci 2>&1 | grep -E 'wanted|got|EINTEGRITY'

# Rule out / repair the local cache
npm cache verify
npm cache clean --force && npm ci

# Which registry/proxy is in use?
npm config get registry
grep -i registry .npmrc ~/.npmrc 2>/dev/null

# Compare lockfile hash to the public registry's recorded integrity
npm view <pkg>@<ver> dist.integrity
npm view <pkg>@<ver> dist.tarball

# Regenerate the lockfile entry (only if genuinely stale)
npm install --package-lock-only && git diff package-lock.json

Conclusion

EINTEGRITY ... wanted X but got Y means the downloaded tarball didn’t match the hash your lockfile trusts — Subresource Integrity refusing to install unverified bytes. Diagnose the mismatch, don’t bypass it:

1. A stale or hand-edited lockfile hash.
2. A corrupt local npm cache (npm cache verify/clean).
3. A proxy/mirror serving re-compressed or altered bytes.
4. A registry switch whose stored hash differs from the lockfile.
5. A republished version — a genuine supply-chain signal to verify.

Read both hashes, clear the cache, compare the proxy’s bytes against the public registry’s dist.integrity, and fix the actual source of the mismatch — regenerating the lockfile only when the recorded hash is legitimately outdated, never disabling integrity to move on.