Yarn: install fails with an integrity checksum mismatch

Hi, it's BlueByte. When yarn install stops with Integrity check failed — or, on modern Yarn, error code YN0018 — nothing is wrong with your code. Yarn compared the tarball it has (downloaded or cached) against the checksum recorded in your yarn.lock, and they don't match, so it refuses to link a package it can't vouch for. We'll walk through what the message means, how to tell which Yarn you're on (the fix differs), why the checksum drifts, how to confirm the cause, fix it either way, and keep it from coming back.

What "Integrity check failed" (and YN0018) is telling you

On Yarn Classic (v1) the failure names the package and the hash it computed:

error Integrity check failed for "left-pad" (computed integrity doesn't match our records, got "sha512-...")

On modern Yarn (Berry, v2+) the same failure carries an error code. Yarn's error index calls YN0018 CACHE_CHECKSUM_MISMATCH and defines it as "The checksum of a package from the cache doesn't match what the lockfile expects." Both forms mean the same thing — the hash Yarn computed for the bytes it has does not equal the hash the lockfile says it should be. Yarn is doing its job: it won't silently install a package whose bytes changed under it.

First, check which Yarn you're actually running

The fix commands and config keys diverge between the two lines, so confirm your version before you touch anything:

yarn --version

1.x is Yarn Classic; 2.x, 3.x, or 4.x is modern Yarn (Berry). A repo can pin its own version through packageManager in package.json or yarnPath in .yarnrc.yml, so the Yarn on your PATH isn't always the one the project uses — run the command from inside the project directory.

Why the checksum stops matching

The hash drifts for a handful of concrete reasons:

• The local cache is corrupt — a partial download, an interrupted install, or a disk issue left a truncated or altered tarball.
• The lockfile was built against a different registry — a private mirror or proxy repackaged the tarball, so its bytes (and hash) differ from the one your lock recorded.
• Someone edited a cache archive by hand while debugging — Yarn's docs call this out as the most common trigger for YN0018.
• You switched Yarn versions or hash algorithms, so an old lock carries checksums the new resolver computes differently.
• Rarely, a registry re-published the same version with different bytes — it shouldn't happen, but private registries sometimes do.

None of these is a bug in your dependency; the mismatch is between the tarball on disk and the lock's record of it.

Read the message: a corrupt cache vs. a changed package

Where the mismatch shows up tells you where to look. If it's a single package and only on your machine, suspect a corrupt local cache. If your whole team or CI hits the same package, suspect the registry or the lockfile. Check what's actually cached:

yarn cache dir     # Classic: prints the global cache path
ls .yarn/cache     # Berry: per-project cache of .zip archives

If the mismatch survives a fresh clone on a colleague's machine, the lockfile itself carries the wrong checksum and needs regenerating — not just a cache wipe.

Fix it on modern Yarn (Berry)

Berry's cleanest fix is to purge the offending entry and refetch. The checksumBehavior setting decides what happens on a mismatch — throw (the default), reset, update, or ignore. Use reset for one run to purge and re-download:

YARN_CHECKSUM_BEHAVIOR=reset yarn install

Per the docs, reset means "the cache entry will be purged and fetched anew." If you've verified the new bytes are legitimate — say a trusted mirror — refetch and re-verify every checksum instead:

yarn install --check-cache

The docs describe --check-cache as "always refetch the packages and ensure that their checksums are consistent." As a last resort, update writes the computed hash back into yarn.lock — only do that when you trust the source of the new bytes.

Fix it on Yarn Classic (v1)

Classic has no checksumBehavior; you clear the cache and reinstall. Remove the stale node_modules and its integrity marker, clean the cache, then install fresh:

yarn cache clean
rm -rf node_modules
yarn install

If the lock's recorded hash is the wrong one — for example after moving registries — regenerate it:

yarn install --update-checksums

That "update checksums in the yarn.lock lockfile if there's a mismatch between them and their package's checksum." Commit the corrected lockfile so everyone gets the fixed value.

A real case: a half-downloaded package in CI

A CI job is evicted mid-yarn install. The next build restores the cache from the previous run and fails with YN0018 on react-dom@npm:18.3.1. Only this one package, only in CI — a classic corrupt-cache signature. You change that step to YARN_CHECKSUM_BEHAVIOR=reset yarn install, the runner purges the truncated .zip, refetches it, the hash matches, and the build goes green. Nothing in the lockfile changed, because the recorded checksum was right all along — the cached bytes weren't.

Verify the install is clean and keep it from recurring

Prove it with an immutable install — the flag CI should use anyway:

yarn install --immutable

➤ YN0000: · Done in 3s 421ms

--immutable aborts "if the lockfile was to be modified," so a clean, checksum-matching install exits 0 with no lock changes. To stop the mismatch returning: commit yarn.lock and never hand-edit the cache; pin one Yarn version with packageManager so everyone resolves hashes the same way; and in CI use --immutable (and --immutable-cache on Berry) so a drifting checksum fails the pipeline loudly instead of being silently "fixed."

How this differs from ERESOLVE and a registry 404

A checksum mismatch is about bytes that changed. An ERESOLVE (npm) or a Yarn peer-dependency error is about versions that can't be reconciled — the resolver, not the download. And a 404 Not Found / "couldn't find package" means the version doesn't exist in the registry at all. If the message says the archive or integrity "doesn't match," it's this article; if it says a version can't be resolved or found, no cache wipe will help.