pnpm ERR_PNPM_TARBALL_INTEGRITY "Got unexpected checksum" - Fix in CI

ERR_PNPM_TARBALL_INTEGRITY means a downloaded package tarball did not hash to the integrity pnpm expected from pnpm-lock.yaml. Usually a corrupted download or a poisoned store, not tampering - but worth confirming.

What this error means

pnpm install fails for a specific package with ERR_PNPM_TARBALL_INTEGRITY, reporting an unexpected checksum. A clean re-fetch on a fresh store often succeeds, pointing at a bad download rather than a bad lockfile.

pnpm output

ERR_PNPM_TARBALL_INTEGRITY  Got unexpected checksum for
"https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz"
Expected: sha512-XYZ...
Actual:   sha512-ABC...

Common causes

A corrupted download or flaky mirror

A truncated or mangled tarball from a proxy, mirror, or transient glitch hashes differently from the recorded integrity, so pnpm rejects it.

A poisoned pnpm store or restored cache

A bad tarball cached in the pnpm content-addressable store (or a restored CI store) replays the same integrity error until the store entry is cleared.

The version was republished with different bytes

If a registry served different bytes than the lockfile recorded, the hashes diverge - rare on npmjs.org but possible behind a custom registry.

How to fix it

Clear the store and reinstall

Prune the pnpm store so the bad tarball is re-fetched fresh.

Terminal

pnpm store prune
rm -rf node_modules
pnpm install

Retry past a flaky mirror

Re-run the job - a corrupted fetch usually succeeds on retry.
If it persists for one package, point at the canonical registry to rule out a bad mirror.
Regenerate the lockfile only if a version was genuinely republished.

How to prevent it

Cache the pnpm store keyed on the lockfile, and bust it on integrity errors.
Prefer a reliable registry/mirror for high-volume pipelines.
Commit a clean pnpm-lock.yaml so integrity values are stable.