Blog
6 min read

npm EINTEGRITY "sha512 integrity checksum failed": Causes and Fixes

npm error code EINTEGRITY means a package failed its sha512 checksum. The usual causes, fixes in a safe order, and when it could mean tampering.

npm error code EINTEGRITY means npm downloaded a package tarball and its sha512 hash didn't match the hash npm expected, usually the one recorded in package-lock.json. Most of the time the cause is boring: a corrupted local cache, a lockfile created against a different registry, or a proxy serving a different file. Work through the fixes in order (npm cache verify, then a clean reinstall, then regenerating that one lockfile entry) and check where the mismatch comes from before you overwrite anything, because occasionally it is a sign the package was swapped.

What the error looks like

npm error code EINTEGRITY
npm error sha512-Xk1G...Qw== integrity checksum failed when using sha512: wanted sha512-Xk1G...Qw== but got sha512-9pLm...Ag==. (48213 bytes)

Read it as:

  • wanted: the hash npm expected, usually from the integrity field of your lockfile.
  • got: the hash of the bytes it actually received.
  • (48213 bytes): how much data it got. A suspiciously small number can point to a truncated download or an HTML error page instead of a tarball.

The error doesn't always name the package. Search your package-lock.json for the "wanted" hash to find it:

grep -n "sha512-Xk1G" package-lock.json

The matching entry tells you the package name, version and resolved URL.

Why npm checks integrity at all

Every entry in package-lock.json stores an integrity string, which the npm docs describe as "a sha512 or sha1 Standard Subresource Integrity string for the artifact that was unpacked in this location". When npm downloads that package again, on your machine, a teammate's, or in CI, it hashes the file and compares. If even one byte differs, it stops.

That's a deliberate safety check. A published version on the public registry can't be overwritten with different contents (per npm's unpublish policy, a package@version can never be reused), so the same version should always produce the same hash. A mismatch means something between the registry and your disk changed the file. See package-lock.json explained for more on what the lockfile records.

Common causes

  1. Corrupted npm cache. npm keeps downloaded tarballs in a local cache (under ~/.npm by default on macOS and Linux). An interrupted download, a full disk, or a crash can leave a bad entry.
  2. Lockfile created against a different registry. If someone generated the lockfile through a company mirror (Artifactory, Nexus, Verdaccio, GitHub Packages) and you install from the public registry, or the other way round, the two may not serve byte-identical tarballs for the same version, especially if the mirror rebuilt or repackaged anything.
  3. A proxy or firewall altering downloads. Corporate proxies, antivirus "web shields" and captive portals sometimes return an error page or a modified file instead of the real tarball.
  4. A hand-edited or badly merged lockfile. Resolving a merge conflict in package-lock.json by hand can leave a version from one side and an integrity hash from the other.
  5. Tampering. Rare, but this is the case the check exists for. More on it below.

The fixes, in order

1. Verify the npm cache

npm cache verify

According to the npm cache docs, this garbage-collects unneeded data and verifies the integrity of the cache index and contents. The docs also describe the cache as self-healing: corrupted entries are detected and refetched. Run npm install again afterwards.

If it still fails, you can clear the cache completely:

npm cache clean --force

The docs note this should rarely be needed, which is why it requires --force. It's safe (it's only a cache), it just means npm redownloads everything.

2. Delete node_modules and reinstall from the lockfile

rm -rf node_modules
npm install

In CI, npm ci does the equivalent: it removes any existing node_modules and installs exactly what the lockfile says, never writing to it (per the npm ci docs).

If this works, the problem was local. Your lockfile is fine and you can stop here.

3. Check your registry and proxy setup

Before touching the lockfile, find out where the mismatch comes from:

npm config get registry

Then compare the resolved URL in the failing lockfile entry with that registry. If the lockfile says https://registry.npmjs.org/... and you're configured for a company mirror (or vice versa), that's very likely your answer. Agree as a team on one registry, set it in a project .npmrc file so everyone uses the same one, and commit that file.

You can also ask the registry what hash it publishes for that exact version:

npm view some-package@2.3.1 dist.integrity
  • If this matches the wanted hash in your lockfile, the lockfile is correct and something on your network or machine is changing the download. Don't regenerate the lockfile. Investigate the proxy, mirror or antivirus instead.
  • If it matches the got hash, your lockfile is the odd one out (often a bad merge or a lockfile from a different registry). Regenerating that entry is reasonable.

4. Regenerate just the affected lockfile entry

Reinstall that one package at the same version so npm records a fresh entry:

npm install some-package@2.3.1

If npm keeps the old hash, delete that package's block (the "node_modules/some-package": { ... } entry) from package-lock.json and run npm install again. Review the diff before committing: apart from that package's resolved and integrity lines, the only other change should be the version range in package.json if npm rewrote it (for example from ^2.0.0 to ^2.3.1), which you can put back if you prefer.

5. Last resort: regenerate the whole lockfile

rm -rf node_modules package-lock.json
npm install

This works, but it also upgrades every dependency to the newest version its range allows, which can bring in unrelated changes. Commit first, test afterwards, and only do this once you're confident the mismatch isn't tampering. Our guide to updating dependencies safely covers how to review a big lockfile change.

When EINTEGRITY could mean tampering

The integrity check is one of npm's main defences against a modified package reaching your machine. Treat it seriously if:

  • the mismatch happens for a package fetched from the public registry, through no proxy or mirror, and npm view ... dist.integrity matches your lockfile but the download still doesn't;
  • it appears on one network but not another (for example, only on public Wi-Fi);
  • it affects a package nobody on the team changed recently.

In those cases, don't "fix" it by regenerating the lockfile, because that just records the suspicious file's hash as correct. Instead, try from a different network, let your security team know if you have one, and run:

npm audit signatures

The npm audit docs say this verifies the registry signatures of downloaded packages and their provenance attestations, where the registry provides them. Our npm supply chain security guide covers the wider picture.

Summary

  • EINTEGRITY = the downloaded file's sha512 doesn't match the expected hash.
  • Try npm cache verify, then delete node_modules and reinstall.
  • Check npm config get registry against the lockfile's resolved URLs.
  • Use npm view <pkg>@<version> dist.integrity to see which side is wrong before regenerating anything.
  • Regenerate one entry before regenerating the whole lockfile.
  • A mismatch on the public registry with no proxy involved deserves a closer look.

EasySpawn gives Claude Code a persistent cloud server to run installs and builds, so dependency errors like this get reproduced and fixed in the same environment the app runs in. See how it works or join the waitlist.

Related: What Is package-lock.json? (And Should You Commit It?) · How to Update Your App's Dependencies Safely · npm Supply Chain Security: Install Scripts, Release Cooldowns, Provenance, and Trusted Publishing

Keep reading