Fix it fast
Most likely: npm downloaded bytes that do not match the hash in the lockfile or registry metadata, commonly from a corrupted local cache or a proxy registry serving mismatched metadata and tarballs.
1. Confirm this is your error
npm ERR! code EINTEGRITY
npm ERR! sha512-<hash> integrity checksum failed when using sha512: wanted <hash> but got <hash>
npm ERR! Verification failed while extracting <package>@<version>2. Check the cause
npm cache verify
npm config get registry
npm view <package>@<version> dist.integrity dist.tarball
npm config list3. Apply the safe fix
# Repair local cache first, then run the deterministic install again.
npm cache verify
npm ci
# If the same package still fails, force one fresh local fetch.
npm cache clean --force
npm ci4. Verify it works
npm ci
npm view <package>@<version> dist.integrity dist.tarballDon't use unsafe shortcuts
- Do not delete
package-lock.jsonjust to silenceEINTEGRITY, that accepts new package metadata without review. - Do not ignore this error in CI, it means npm could not verify the package bytes.
- Do not assume this is always local cache corruption if you use a proxy registry.
What This Error Means
This is a content-integrity failure, not an auth or version-not-found error. npm got bytes for a tarball, but those bytes did not match the trusted hash recorded in metadata or the lockfile.
Fix the integrity mismatch
Start with cache and registry mapping, then compare metadata if a proxy registry is involved. Regenerate the lockfile only when you intend to accept new resolved URLs and hashes.
Start with the safe local repair:run npm cache verify, remove node_modules, and retry with npm ci when a lockfile exists.
If there is no lockfile, run npm install intentionally to generate one, review the dependency change, and commit the lockfile before using npm ci in CI.
Do not delete package-lock.json just to silence the error, only regenerate it when you intend to accept new resolved URLs and integrity values.
If the package is scoped, fix .npmrc so @your-scope:registry=... points at the registry that actually owns the package.
If cache verification does not repair the download, force a fresh local fetch with npm cache clean --force, then retry the install.
If using a proxy registry, clear or re-fetch the affected package/version in the proxy cache and compare dist.integrity plus dist.tarball against upstream before retrying.
If the mismatch only happens behind a corporate proxy or antivirus layer, test the same package download from a network path without that middlebox and fix the proxy exception or TLS-inspection policy.
Why It Happens
Most EINTEGRITY cases come from mismatched bytes and metadata: local cache state, lockfile state, scoped registry configuration, or a proxy cache serving inconsistent package data.
Local cache corruption:the npm cache contains an incomplete or corrupted tarball, often after an interrupted download or a shared CI cache restore.
Lockfile/registry mismatch:package-lock.json expects one tarball hash, but the active registry returns metadata or a tarball that does not match that hash.
Scoped registry drift:a scoped package is resolved from a different registry than expected because .npmrc maps @scope to the wrong endpoint.
Proxy registry cache mismatch:a proxy or remote registry serves stale metadata with a newer or different tarball for the same package version.
Network modification:a proxy, antivirus tool, or TLS-inspection layer truncates or rewrites the tarball response before npm can verify it.
Verify the Fix
Do not stop at "the command returned 0 once." Re-run the real workflow from the same machine or runner and make sure the original symptom is actually gone.
Run npm ci from a clean working tree and confirm the same package/version installs without EINTEGRITY.
Run npm view <pkg>@<version> dist.integrity dist.tarball against the active registry and confirm it matches the lockfile entry you are using.
If you use a proxy registry, verify the install works once with a cold proxy/cache path and once after the cache is warm.
If CI was failing, clear the CI dependency cache once and confirm the next run succeeds without regenerating the lockfile unexpectedly.
Manual checksum validation
If the main log is noisy or truncated, these checks let you isolate the failing layer directly and confirm whether you are dealing with configuration, access, trust, or local environment state.
Identify the exact package and version from the EINTEGRITY output before changing the lockfile.
Print the active registry and scoped overrides from the failing environment:npm config get registry, npm config get @your-scope:registry, and npm config list
Get the expected integrity and tarball URL from the active registry:npm view <pkg>@<version> dist.integrity dist.tarball
If a lockfile exists, inspect the same package entry there and compare its resolved and integrity values with the registry output.
Download the tarball and compute SHA-512:curl -L <tarball-url> -o pkg.tgz && openssl dgst -sha512 -binary pkg.tgz | openssl base64 -A
If using a proxy registry, compare upstream and proxy metadata with npm view <pkg>@<version> dist.integrity dist.tarball --registry=https://registry.npmjs.org/ and the same command against your proxy registry.
If the proxy metadata and upstream metadata differ for the same version, clear or refresh the affected package/version in the proxy cache before regenerating local state.
How npm verifies package integrity
This is the part worth understanding if the quick fix did not hold. It explains what npm is trying to do at the moment the error appears.
npm reads the package version, tarball URL, and SRI integrity value from package-lock.json and/or registry metadata. During install, npm downloads the tarball, hashes the downloaded bytes, and compares that hash with the expected sha512-... integrity value before it extracts the package.
An EINTEGRITY failure means npm reached something that looked like the package tarball, but the bytes did not match the hash npm expected for that exact package version. That can be a local cache problem, but in proxy-registry setups it can also mean metadata and tarball cache entries came from different upstream states.
Prevent It From Coming Back
Once the immediate issue is fixed, a little standardization here saves a lot of repeated incidents across developer laptops, CI runners, and container images.
Use deterministic installs with npm ci in CI and keep package-lock.json committed.
Pin Node and npm versions in CI so lockfile format and integrity handling do not drift between environments.
Keep scoped registry mappings in one reviewed .npmrc instead of relying on per-runner global config.
For proxy registries, monitor metadata/tarball cache health and provide a documented way to purge a single affected package/version.
Avoid force-publishing or mutating tarballs for an existing version, publish a new version when package bytes change.
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