A Yarn checksum mismatch means the package archive Yarn has or just downloaded does not match the checksum recorded in the lockfile. Do not reset it to make the error go away. First find out why: a registry change, a corrupted cache, or a tampered package.
What Yarn does by default
The Yarn configuration reference lists checksumBehavior with a default of throw: Yarn raises an exception when a checksum does not match. Other options are update, which syncs the lockfile to the cached checksum, reset, which purges and refetches the cache entry, and ignore, which skips the check.
Those four options are very different. Throw protects you. Ignore removes protection entirely. Update changes your lockfile to trust whatever the cache holds. Reset trusts whatever the registry returns now.
Likely causes
- A corrupted or partially written cache file on one machine.
- A package that was republished or changed at the same version, which good registries try to prevent.
- A lockfile merge that mixed entries from different resolutions.
- A tampered archive, from a compromised mirror, proxy or cache.
The first three are common and benign. The fourth is the one you cannot rule out by guessing.
How to investigate
- Re-run the install on a clean machine or container. If it passes there, suspect the local cache.
- Compare the failing package and version against a fresh download from your primary registry.
- Use Yarn's check cache option, which the install reference says refetches every package and verifies checksums against the lockfile and any existing cache files.
- Look at the git history of the lockfile for the entry. If it changed recently, ask who changed it and why.
- Only after you know the cause, choose reset or update, and document the reason in the pull request.
| Option | Safe to use casually? |
|---|---|
| throw | Yes, it is the default |
| reset | Only after you know the cache is bad |
| update | Rarely, since it rewrites the lockfile to match the cache |
| ignore | No |
The npm equivalent is covered in the npm integrity mismatch error.
Common mistakes
The most common mistake is setting checksumBehavior to ignore after a failure so the pipeline goes green. That keeps the symptom hidden and removes the check for every future install too. The next is deleting the lockfile entry and regenerating it without comparing the old and new values, which discards the evidence. Finally, teams sometimes fix it on one laptop and never find out that a shared cache or mirror holds the odd file. Find the source, then fix the source.
Quick check
Is a checksum mismatch always an attack?
No. Cache corruption and lockfile merge mistakes are common. But treat it as unexplained until you know the cause.
What is the default checksumBehavior?
throw, meaning Yarn raises an exception on a mismatch.
Safeguard monitors packages in your SBOM for newly reported malicious versions. Try the free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
