On pnpm?

pnpm workspace or store integrity failing? We sort it out.

pnpm is fast and disk efficient when its store, lockfile and workspace graph all agree. When they disagree, installs fail in ways npm and Yarn users never had to think about, and the error messages assume you already know what the store is. We walk it through to the real cause.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

pnpm-install.log

still failing

What it is

pnpm at a glance

pnpm is a fast, disk space efficient package manager for Node.js, created by Zoltan Kochan and first released in 2017. Instead of copying every package into every project's node_modules, it keeps a single content addressable store on disk and hard links packages from there, which saves gigabytes on machines with many projects.

It supports workspaces natively through the workspace: protocol, enforces strict dependency resolution so packages cannot import what they did not declare, and has become the default package manager for several large open source projects. It is distributed as a single binary and now also has a Rust rewrite of its CLI underway.

Type
JavaScript package manager and workspace tool
First released
2017
License
MIT, free and permissive
Maintained by
Zoltan Kochan and the pnpm community
Typically used for
Node.js dependency management, monorepo workspaces, CI install performance, disk efficient package installs

The honest version

pnpm pros and cons

No technology is all upside. This is where pnpm earns its place and where it tends to cause trouble.

Where pnpm is strong

  • Disk savings are dramaticThe content addressable store means one copy of React on disk is shared across every project and every version pin that resolves to it, which matters on laptops and CI caches alike.
  • Strict resolution catches phantom dependenciesPackages can only import what they declare, which exposes the quiet bugs where code worked only because an unrelated dependency happened to hoist the module.
  • Workspaces are a first class featureThe workspace: protocol and pnpm --filter give you a proper monorepo workflow without a second tool bolted on.
  • Faster installs on clean machinesResolution is parallelised, downloads are deduplicated at the store level, and a warm store can skip the download step entirely, which cuts cold CI install time significantly.
  • Deterministic by defaultThe lockfile is strict, resolution is reproducible, and the same command on two machines produces the same node_modules layout.
  • Good escape hatches when you need themshamefully-hoist, public-hoist-pattern, auto-install-peers and overrides exist for the cases where strict mode genuinely cannot work, so you are not stuck.

Where pnpm bites

  • Store integrity errors are intimidatingA corrupted store or a store moved between machines produces an error about unexpected store location that leaves most teams reaching for rm -rf rather than reading the message.
  • Workspace protocol surprises toolingSome external tools, bundlers and publish pipelines do not know what workspace:^ means and pass it through to a registry that rejects it.
  • Peer dependency strictnesspnpm reports peer dependency issues npm would have ignored, which is technically correct but often breaks installs that worked yesterday on a different tool.
  • Build script allow list frictionNative modules like sharp or better-sqlite3 are blocked from running their install scripts by default on newer versions, and installs look successful while the native binary is missing.
  • Migrating off is harder than migrating onThe workspace: protocol and strict resolution leak into package.json files, so going back to npm or Yarn later takes more than a lockfile swap.
  • CI disk cache strategies take tuningThe store on CI needs to be cached correctly, and a naive cache key invalidates often, which gives up most of the install speed pnpm was chosen for.

Sound familiar?

Common pnpm problems we fix

The pnpm problems that bring people to us, and what you have once each one is fixed.

ERR_PNPM_WORKSPACE_PKG_NOT_FOUND

workspace: protocol fails to resolve

A dependency uses workspace:^ but the matching package is not in the workspaces list, or its name does not match the one the consumer imported. The fix is in pnpm-workspace.yaml, not the lockfile.

Workspace graph resolves cleanly

ERR_PNPM_UNEXPECTED_STORE

Store integrity error on a shared machine

node_modules was linked against one store and the install now runs against another, usually after moving a repo between users or containers. Wiping the project node_modules without touching the store resolves it.

Store and project aligned

ERR_PNPM_TARBALL_INTEGRITY

Tarball checksum does not match

A proxy or registry served the wrong bytes, or the lockfile was edited by hand. We refresh the specific entry rather than regenerating the whole lockfile.

Lockfile trusted again

ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY

Lockfile is out of date

A dependency was added to package.json but the lockfile was never regenerated, often because CI ran install with --frozen-lockfile and silently diverged on local machines.

Lockfile matches package files

ignored build scripts: sharp, puppeteer

Native modules silently skipped

pnpm now requires explicit approval before running package install scripts, so sharp, puppeteer and better-sqlite3 install without their native binaries and crash at runtime.

Native binaries built, runtime stable

Issues with peer dependencies

Peer dependency warnings turn into failures

React 19 lands in one package, another still wants React 18, and pnpm refuses to pretend the conflict is not there. Overrides or an upgrade plan fix it; silencing the warning does not.

Peers consistent across packages

ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL

pnpm -r halts on the first failing package

A recursive command stops the whole run on the first error, which hides later failures. We use --no-bail during triage and the default behaviour on green pipelines.

All failures visible in one run

ENOSPC: no space left on device

Store fills the disk

A CI runner that never prunes the pnpm store eventually runs out of room. Periodic pnpm store prune and a sensible store path solve it.

Store size under control

What we do

pnpm help, from rescue to workspace design

Call us for one broken install, or let us set up the whole workspace properly.

Rescue
Red installs, store integrity errors, or CI that takes twenty times as long as local. We trace the specific cause and show the fix.
Monorepo setup
pnpm-workspace.yaml, filter patterns, workspace: protocol and strict resolution tuned against the way your teams actually work.
CI install performance
Store caching, offline mode, frozen lockfile usage and sharded jobs set up so pnpm installs in CI match what you see on a developer laptop.
Native module reliability
Build script approvals, prebuilt binaries and fallback patterns so sharp, puppeteer and database drivers install the same way in every environment.
Migrations
Moves from npm or Yarn done in a measured pass with the old lockfile retained until the new one is fully trusted on CI and on every developer machine.
Managed Tech
Lockfile audits, dependency upgrades, periodic store health checks and a team on call when a surprise peer dependency conflict takes a release down.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running pnpm alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

pnpm questions

Something else? Call+1 737 727 7327

Why does pnpm complain about peer dependencies that npm ignored?

npm quietly installed a peer dependency that did not satisfy the requested range and left you to find out at runtime. pnpm refuses to do that and prints every unsatisfied peer during install. The warnings are usually real, and the fix is either an overrides entry, a version bump on one side, or genuinely accepting the mismatch with auto-install-peers off.

How do we stop sharp or better-sqlite3 from failing at runtime?

Newer pnpm versions require an explicit list of packages whose build scripts are allowed to run. Add them to the onlyBuiltDependencies field in package.json or pnpmfile, reinstall, and the native binaries get built the same way in every environment. The default of ignoring the scripts is a security measure, not a bug.

Why is our CI install so much slower than local?

Usually the pnpm store is not cached, or it is cached under a key that invalidates on every lockfile change. We set the store path explicitly, cache it against the lockfile hash, and use pnpm install --frozen-lockfile so the resolution step is skipped entirely when nothing changed.

Can we migrate from npm or Yarn to pnpm without breaking things?

Yes, and it is one of the lower risk migrations in the ecosystem because the package.json files barely change. We import the existing lockfile, run a first install to generate the pnpm one, work through the peer dependency warnings, and verify every workspace command still behaves the same way.

What does the unexpected store error actually mean?

The node_modules folder has symlinks pointing at a store on one machine and you are now running on another, or the store was moved. Clearing just node_modules and running install again rebuilds the links against the current store without touching the shared cache.

How much does pnpm help cost?

The quote is free. Send over a failing install log and your pnpm-workspace.yaml, and we come back with a price and a plan before anything is changed.

Free estimate

pnpm giving your team grief?

Tell us what you're running and what's going wrong. A person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.