yarn "Integrity check failed" in CI - Fix Lockfile and Cache Integrity

By Kaveh Alemi·Latchkey

Yarn records integrity hashes for installed packages. An integrity check failure means the on-disk tree no longer matches the lockfile, from drift or a corrupted cache.

What this error means

yarn install or yarn check fails reporting Integrity check failed, sometimes naming the file lock or package whose hash disagrees. A clean install often succeeds.

yarn

error Integrity check failed
error Found 1 errors.
info Lockfile is out of sync with the integrity file.

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

A corrupted or stale yarn cache

Cached artifacts that no longer match the lockfile produce a hash mismatch, which clears on a fresh fetch.

yarn.lock diverged from the installed tree

A partial or hand-edited lockfile encodes hashes that do not match what gets installed.

How to fix it

Clear the cache and reinstall

Remove node_modules and clean the yarn cache.
Reinstall so hashes are recomputed from fresh downloads.

Terminal

rm -rf node_modules
yarn cache clean
yarn install

Regenerate the lockfile if it is genuinely stale

Delete yarn.lock and reinstall to rebuild integrity data.
Commit the refreshed lockfile.

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

Cache the yarn cache keyed on yarn.lock, keep the lockfile in sync, and pin a registry. On Latchkey managed runners a transient corrupted-cache integrity failure is auto-retried against a cached registry, so it usually clears on its own.

Frequently asked questions

What causes yarn "Integrity check failed" in CI?

There are 2 common causes: a corrupted or stale yarn cache and yarn.lock diverged from the installed tree. Cached artifacts that no longer match the lockfile produce a hash mismatch, which clears on a fresh fetch.

How do I fix yarn "Integrity check failed" in CI?

There are 2 fixes depending on which cause you have: clear the cache and reinstall and regenerate the lockfile if it is genuinely stale. Work through them in order, since the first is the most common.

What does yarn "Integrity check failed" in CI actually mean?

yarn install or yarn check fails reporting Integrity check failed, sometimes naming the file lock or package whose hash disagrees.

How do I stop yarn "Integrity check failed" in CI happening again?

Cache the yarn cache keyed on yarn.lock, keep the lockfile in sync, and pin a registry.