Fix: Yarn Integrity Check Failed – Expected and Got Different Results

The Error

When running yarn install or starting your project, you see one of these messages:

Yarn v1 (Classic):

error Integrity check failed for "lodash" (computed integrity doesn't match our records, got "sha512-abc123...")
info This usually happens when the "yarn.lock" or "node_modules" is corrupted.

Or:

error An unexpected error occurred: "Lockfile does not satisfy expected package requirements.
Expected react@^18.2.0, got react@17.0.2"

Yarn v2/v3/v4 (Berry):

YN0018: │ lodash@npm:4.17.21: The remote archive doesn't match the expected checksum
Expected: sha512-xyz789...
Got: sha512-abc123...

Or:

YN0002: │ my-app@workspace:. doesn't provide react (p1a2b3), requested by react-dom

All of these come down to the same fundamental problem: Yarn expected a package to have specific contents (identified by a hash or checksum), but the actual contents it downloaded or found on disk are different. Yarn refuses to continue because using a package with unexpected contents could mean anything from a minor version bump to a supply chain attack.

Why This Happens

Yarn uses integrity hashes (SHA-512 checksums) to verify that every package it installs matches exactly what was recorded when the lockfile was created. The lockfile (yarn.lock) stores the expected checksum for every resolved package. When Yarn downloads a package or reads it from cache, it computes a checksum and compares it to the one in the lockfile.

A mismatch means something changed. The most common causes:

• Corrupted local cache. Yarn caches downloaded packages locally to avoid re-downloading them. If a cached archive gets corrupted (disk error, interrupted download, antivirus software modifying files), the checksum won’t match.
• Stale lockfile. The yarn.lock was generated with one set of package versions, but package.json has been modified since then (by you, by a colleague, or by a merge). The lockfile expectations no longer match what needs to be installed.
• Registry republished a package. Although npm strongly discourages it, a package author can unpublish and republish the same version with different contents within a short window. This changes the checksum on the registry side while your lockfile still has the old one.
• Network or proxy issues. A corporate proxy, VPN, or CDN edge node served a cached or modified version of the package tarball. This is especially common with corporate HTTP proxies that inject content or when switching between different network environments.
• Switching between Yarn versions. Yarn v1 and Yarn Berry use different lockfile formats and different integrity verification mechanisms. Running yarn install with a different Yarn version than the one that generated the lockfile can trigger checksum mismatches.
• CI cache poisoning. Your CI pipeline cached node_modules or the Yarn cache from a previous run, and that cached data is now stale or corrupted. This is one of the most common causes when the error only appears in CI but not locally.

Why this matters: Integrity checking exists to protect you from supply chain attacks. When a package’s checksum does not match, it could mean a corrupted download — or it could mean someone tampered with the package on the registry. Never use checksumBehavior: ignore in production; always investigate the mismatch first.

Fix 1: Clean the Yarn Cache

The most common cause is a corrupted cache entry. Clearing the cache forces Yarn to re-download all packages fresh from the registry.

Yarn v1 (Classic):

yarn cache clean
yarn install

To clear the cache for a specific package only:

yarn cache clean lodash
yarn install

Yarn Berry (v2/v3/v4):

yarn cache clean --all
yarn install

In Berry, the cache location depends on your configuration. By default, Berry stores its cache in .yarn/cache/ inside your project directory (for zero-installs) or in a global location. If you want to see where your cache is:

yarn config get cacheFolder

You can also manually delete the cache directory:

rm -rf .yarn/cache
yarn install

If a corrupted cache was the problem, this fixes it immediately. Yarn will re-download every package and verify the new checksums against the lockfile.

Fix 2: Delete node_modules and yarn.lock, Then Reinstall

If cleaning the cache didn’t work, the lockfile itself may contain stale or incorrect data. Start completely fresh:

Yarn v1:

rm -rf node_modules yarn.lock
yarn install

Yarn Berry:

rm -rf node_modules .yarn/cache .pnp.cjs .pnp.loader.mjs yarn.lock
yarn install

On Windows (Command Prompt):

rmdir /s /q node_modules
del yarn.lock
yarn install

This forces Yarn to resolve the entire dependency tree from scratch based solely on what’s in package.json. It generates a new yarn.lock with fresh checksums from the registry. If you get errors about missing modules after reinstalling, see Fix: Error Cannot find module in Node.js.

Real-world scenario: Your CI pipeline passes on Monday but fails with an integrity error on Tuesday, even though no code changed. The most likely cause is a stale CI cache — the cached .yarn/cache directory contains archives from a previous lockfile, and the checksums no longer match after a colleague merged a dependency update.

Important: Deleting yarn.lock means Yarn will resolve to the latest versions that satisfy your package.json ranges. This could pull in newer minor or patch versions than you had before. If you need reproducible builds, commit the new yarn.lock and verify your tests pass before deploying.

Fix 3: Use yarn install --check-files

In Yarn v1, there’s a flag specifically designed for this situation:

yarn install --check-files

This tells Yarn to verify that all files in node_modules are correct and haven’t been tampered with or corrupted. If it finds any issues, it re-downloads and reinstalls the affected packages without nuking the entire node_modules directory.

This is a less destructive alternative to deleting everything. It keeps your existing installs intact and only fixes what’s broken.

You can also make this the default behavior by adding it to your .yarnrc file:

--install.check-files true

Note that --check-files is a Yarn v1 feature. In Yarn Berry, integrity checking is always enabled and there’s no equivalent flag because Berry validates package integrity on every install by default.

Fix 4: Fix CI Caching Issues

If the integrity check only fails in CI (GitHub Actions, GitLab CI, CircleCI, Jenkins), the problem is almost always a stale or corrupted cache.

GitHub Actions

A common mistake is caching node_modules directly. Don’t do that. Cache the Yarn cache directory instead, and let Yarn populate node_modules from the cache on each run:

- name: Get Yarn cache directory
  id: yarn-cache
  run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT

- name: Cache Yarn packages
  uses: actions/cache@v4
  with:
    path: ${{ steps.yarn-cache.outputs.dir }}
    key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
    restore-keys: |
      ${{ runner.os }}-yarn-

- name: Install dependencies
  run: yarn install --frozen-lockfile

The --frozen-lockfile flag (Yarn v1) or --immutable flag (Yarn Berry) ensures that yarn.lock is not modified during install. If the lockfile is out of date, the install fails immediately instead of silently updating it — which is what you want in CI.

For Yarn Berry:

- name: Install dependencies
  run: yarn install --immutable

Invalidate the cache

If your CI builds suddenly start failing with integrity errors, the quickest fix is to bust the cache. Most CI systems let you change the cache key:

# Change v1 to v2 (or any new value) to invalidate the cache
key: ${{ runner.os }}-yarn-v2-${{ hashFiles('**/yarn.lock') }}

GitLab CI

cache:
  key:
    files:
      - yarn.lock
  paths:
    - .yarn/cache/

Don’t cache node_modules

Caching node_modules directly is fragile because the directory contains platform-specific binaries and symlinks that break when restored on a different machine or OS version. Always cache the package manager’s cache directory and let the package manager handle node_modules.

Fix 5: Handle Yarn v1 vs. Yarn Berry Differences

Yarn v1 (Classic) and Yarn Berry (v2, v3, v4) handle integrity very differently. If you’re migrating between versions or working on a team where different developers use different Yarn versions, this can cause checksum mismatches.

How to check your Yarn version

yarn --version

Yarn v1 integrity behavior

Yarn v1 stores an integrity file at node_modules/.yarn-integrity. This file records metadata about the install — the exact flags used, the Node.js version, the lockfile checksum, and the list of installed packages. When you run yarn install, Yarn compares the current state against this file. If anything differs, it triggers the integrity check failure.

You can force Yarn to regenerate this file by deleting it:

rm node_modules/.yarn-integrity
yarn install

Yarn Berry integrity behavior

Berry uses a completely different architecture. Instead of node_modules, Berry can use Plug’n’Play (PnP), which stores packages as zip archives in .yarn/cache/ and uses a .pnp.cjs file to tell Node.js where to find them. Integrity checking in Berry compares the checksum of each cached zip archive against the checksum stored in yarn.lock.

If you’re migrating from v1 to Berry, you need to remove all v1 artifacts first:

rm -rf node_modules .yarn-integrity
yarn install

.yarnrc.yml configuration for Berry

Berry uses .yarnrc.yml (not .yarnrc) for configuration. Relevant settings for integrity issues:

# Where to store the cache
cacheFolder: ./.yarn/cache

# Checksum behavior: "throw" (default), "update", or "ignore"
checksumBehavior: throw

# Use hardlinks instead of copies (reduces disk space)
nmMode: hardlinks-local

The checksumBehavior setting controls what happens when a checksum mismatch is detected:

• throw (default) — Fails the install with an error. This is the safest option.
• update — Silently updates the checksum in the lockfile to match the downloaded package. Use this temporarily to fix widespread checksum mismatches, but switch back to throw afterward.
• ignore — Skips checksum verification entirely. Do not use this in production. It defeats the purpose of integrity checking.

If you’re seeing widespread checksum mismatches after a registry migration or Yarn upgrade, temporarily setting checksumBehavior: update and running yarn install will regenerate all checksums:

# Temporarily allow checksum updates
echo 'checksumBehavior: update' >> .yarnrc.yml
yarn install

# Revert to strict checking
sed -i '/checksumBehavior: update/d' .yarnrc.yml

Then commit the updated yarn.lock.

Fix 6: Resolve Checksum Mismatches from the Registry

Sometimes the issue isn’t local at all — the registry itself is serving different content than what your lockfile expects. This can happen when:

• A package was unpublished and republished (within npm’s 72-hour window for new packages).
• You switched registries (e.g., from the public npm registry to a private Artifactory or Verdaccio instance).
• A corporate proxy is modifying or caching package tarballs.

Verify the registry URL

Check which registry Yarn is configured to use:

Yarn v1:

yarn config get registry

Yarn Berry:

yarn config get npmRegistryServer

Make sure it matches what your team or project expects. If you recently switched from a private registry to the public one (or vice versa), the checksums will be different because private registries may repackage tarballs.

Regenerate checksums for a specific package

If only one or two packages have checksum mismatches, you can force Yarn to re-resolve them:

yarn upgrade lodash

Or for Yarn Berry, remove the cached archive and reinstall:

rm .yarn/cache/lodash-npm-*.zip
yarn install

Network and proxy issues

If you’re behind a corporate proxy, Yarn’s downloads may be intercepted or modified. Symptoms include integrity failures that only happen on certain networks. Configure Yarn to use your proxy correctly:

Yarn v1 (.yarnrc):

proxy "http://proxy.company.com:8080"
https-proxy "http://proxy.company.com:8080"
strict-ssl false

Yarn Berry (.yarnrc.yml):

httpProxy: "http://proxy.company.com:8080"
httpsProxy: "http://proxy.company.com:8080"
enableStrictSsl: false

Setting strict-ssl or enableStrictSsl to false is a security trade-off. Only do this if you understand the implications and your organization’s proxy requires it.

If your environment variables for proxy or registry configuration aren’t being picked up, see Fix: Environment Variable is Undefined for common causes.

Fix 7: Handle Platform-Specific Package Failures

Some packages include platform-specific binaries (e.g., esbuild, swc, sharp). These packages publish different tarballs for different operating systems and CPU architectures. If your lockfile was generated on macOS but you’re installing on Linux (common in CI), or if you switch between x64 and ARM, the expected checksum won’t match the downloaded tarball.

Yarn Berry handles this with the supportedArchitectures setting in .yarnrc.yml:

supportedArchitectures:
  os:
    - linux
    - darwin
    - win32
  cpu:
    - x64
    - arm64

This tells Yarn to download and cache binaries for all listed platforms, which prevents checksum mismatches when the lockfile is shared across different environments.

Yarn v1 doesn’t have this setting. The workaround is to regenerate the lockfile on the target platform, or use --ignore-platform to skip platform checks:

yarn install --ignore-platform

If dependency resolution itself is the problem rather than integrity checks, and you’re seeing conflicts during install, you might find the approach in Fix: npm ERR! ERESOLVE unable to resolve dependency tree useful — the concepts of peer dependency resolution apply to Yarn as well.

Still Not Working?

1. Verify your Node.js and Yarn versions. Different versions of Node.js ship with different versions of the crypto module, which can produce different hashes in edge cases. Run node --version and yarn --version and make sure they match what your team uses. Consider using a .node-version or .nvmrc file and a packageManager field in package.json to pin versions.

2. Check disk space. On CI runners or Docker containers, running out of disk space during package downloads can produce truncated archives that fail integrity checks. Check available space with df -h.

3. Look at the full error output. The integrity error message includes both the expected and actual checksums. If the “got” hash is consistently the same wrong value, the registry is serving different content. If the “got” hash is different every time, you likely have a network issue (proxy, VPN, or unstable connection) corrupting downloads.

4. Try a different network. If you’re on a VPN or corporate network, try disconnecting and running yarn cache clean && yarn install on a direct internet connection. If it works, your network is modifying the downloaded packages.

5. Check for lifecycle script issues. Some packages run postinstall scripts that modify their own files after installation. If these scripts fail or produce different output on different runs, the integrity of the installed package changes. Check for lifecycle script errors if you see warnings about postinstall or prepare scripts.

6. Use yarn why to understand the dependency. If a specific package keeps causing integrity failures, check why it’s being installed and whether you can replace or remove it:

   yarn why lodash

7. Try resolving TypeScript-related module issues separately. If your integrity check failure is happening alongside TypeScript import errors, those may be independent problems. See Fix: Cannot find module or its corresponding type declarations in TypeScript for TypeScript-specific module resolution.

8. File a bug report. If you’ve exhausted all options and the problem persists, search the Yarn GitHub issues for your specific error message. Include your Yarn version, Node.js version, operating system, and the full error output. If you’re using Yarn Berry, run yarn --version and include the exact version number (e.g., 4.1.1) since behavior can change between minor releases.

Related: If you’re running into other npm or Node.js installation problems, see Fix: Error Cannot find module in Node.js and Fix: npm ERR! ERESOLVE unable to resolve dependency tree.