yarn "Integrity check failed" / checksum mismatch - Fix in CI

By Kaveh Alemi·Latchkey

yarn records a checksum for every resolved package in yarn.lock and verifies it on install. A mismatch means the fetched bytes differ from what the lockfile expects - typically a corrupted cache or mirror, not tampering.

What this error means

yarn install fails with "Integrity check failed" (or a checksum-mismatch message in Berry) for a specific package. A clean cache and re-fetch usually fixes it, indicating corruption rather than a wrong lockfile.

yarn output

error https://registry.yarnpkg.com/.../pkg.tgz:
Integrity check failed for "pkg" (computed integrity doesn't match
our records, got "sha512-ABC..." expected "sha512-XYZ...")

Diagnose it: reproduce the CI install locally

Install failures are usually environment drift rather than a broken lockfile: a different package-manager major, a different Node version, or a cache that is being restored from a run with different inputs. Reproduce the CI conditions before changing the lockfile, because regenerating it hides the real cause.

Terminal

# match the runner exactly, then install from a clean slate
node --version && npm --version
rm -rf node_modules
npm ci --foreground-scripts

# if that succeeds locally but fails in CI, the difference is the cache
# or the package-manager version, not your lockfile

Common causes

Corrupted yarn cache or download

A damaged tarball in the yarn cache, or a truncated fetch from a mirror, hashes differently from the lockfile’s recorded checksum.

A mirror serving different bytes

A proxy/mirror that returns a re-packaged or differing tarball than the canonical registry breaks the integrity check.

How to fix it

Clean the cache and reinstall

Force a fresh fetch so the cached bad tarball is discarded.

Terminal

yarn cache clean
rm -rf node_modules
yarn install --immutable

Rule out a bad mirror

Re-run the job - a transient corrupted fetch usually recovers.
Point at the canonical registry to confirm the mirror is the culprit.
Regenerate yarn.lock only if you have confirmed the published bytes legitimately changed.

Verify the fix survives a cold cache

A green run immediately after a fix often proves nothing, because it restored a cache written before the change. Force a cold install once to confirm the fix is real.

.github/workflows/ci.yml

# temporarily bust the cache key to prove the fix on a cold runner
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: npm
    cache-dependency-path: package-lock.json
# then bump this suffix once, run, and remove it
#   key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}-v2

How to prevent it

Bust the yarn cache when integrity errors recur.
Prefer a reliable registry/mirror in CI.
Keep yarn.lock committed and stable.

Frequently asked questions

What causes yarn "Integrity check failed" / checksum mismatch?

There are 2 common causes: corrupted yarn cache or download and a mirror serving different bytes. A damaged tarball in the yarn cache, or a truncated fetch from a mirror, hashes differently from the lockfile’s recorded checksum.

How do I fix yarn "Integrity check failed" / checksum mismatch?

There are 2 fixes depending on which cause you have: clean the cache and reinstall and rule out a bad mirror. Work through them in order, since the first is the most common.

What does yarn "Integrity check failed" / checksum mismatch actually mean?

yarn install fails with "Integrity check failed" (or a checksum-mismatch message in Berry) for a specific package.

How do I stop yarn "Integrity check failed" / checksum mismatch happening again?

Bust the yarn cache when integrity errors recur. The prevention section lists 3 changes that keep it from recurring.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.