What This Error Means
npm downloaded a package tarball whose checksum did not match the expected integrity value (lockfile/metadata mismatch).
Read this as a precise clue about which part of the workflow broke first. Once you know the failing layer, the fix path gets much shorter.
Fix the integrity mismatch
The fastest fixes here come from checking the immediate failing layer before you change anything unrelated. Make one correction at a time and re-test from the same environment.
Check which registry npm is using:npm config get registry
If the package is scoped, verify scope registry mapping in .npmrc (example: @your-scope:registry=...).
Verify the npm cache first:npm cache verify (then retry).
If package-lock.json exists, remove node_modules and run npm ci (do not delete the lockfile unless you intend to regenerate it).
If you do not have a lockfile, run npm install to generate one intentionally and commit it (then CI can use npm ci).
If cache verification does not help, force a re-download:npm cache clean --force (then retry).
If using a proxy registry, confirm it is fully synced and not serving mixed metadata/tarballs for the same version.
Why It Happens
Usually this comes down to the npm cache contains a corrupted tarball (common after interrupted downloads), a proxy/cache registry served stale metadata or a different tarball for the same version, or network middleboxes (proxies, antivirus) modified or truncated the tarball download.
Verify the Fix
Re-run the install and confirm EINTEGRITY no longer appears.
If you are using a proxy registry, verify installs succeed both with and without cache warm state.
Manual checksum validation
Get the expected integrity and tarball URL:npm view <pkg>@<version> dist.integrity dist.tarball
Download the tarball and compute SHA-512:curl -L <tarball-url> -o pkg.tgz && openssl dgst -sha512 -binary pkg.tgz | openssl base64 -A
Compare the computed value to the sha512-... integrity string.
If you have a proxy registry, repeat the same check against the proxy and the upstream registry.
Examples
npm ERR! code EINTEGRITY
npm ERR! sha512-<hash> integrity checksum failed when using sha512: wanted <hash> but got <hash>How npm verifies package integrity
npm stores expected SRI integrity values in the lockfile and/or registry metadata. During install, npm downloads the tarball and verifies its checksum before extracting. If the downloaded bytes do not match the expected checksum, npm throws EINTEGRITY.
Prevent It From Coming Back
To prevent this, prefer deterministic installs (npm ci) in CI when you have a lockfile, use a reliable proxy/cache registry and monitor sync health, and avoid force-publishing or mutating tarballs for an existing version.
Docs and source code
github.com/npm/ssri/blob/73adc1554d0b60606a8fb315d47f7afde7fd913e/lib/index.js
Open-source npm dependency code reference tied to this integrity error. - GitHub
this.emit('error', err)
} else if (this.sri && !match) {
const err = new Error(`${this.sri} integrity checksum failed when using ${this.algorithm}: wanted ${this.digests} but got ${newSri}. (${this.size} bytes)`)
err.code = 'EINTEGRITY'
err.found = newSri
err.expected = this.digests
err.algorithm = this.algorithm