Yarn "Cannot find the node_modules state file" in CI

With the node-modules linker, Yarn Berry records what it installed in node_modules/.yarn-state.yml. If that state file is missing while node_modules exists, Yarn cannot reconcile the install.

What this error means

Yarn commands fail with "Cannot find the node_modules state file". It typically happens when a cache restored node_modules but not the state file, or only part of node_modules survived.

Usage Error: Cannot find the node_modules state file - running an install
might help (findPackageLocation)

Common causes

Partial cache restore

node_modules was cached but .yarn-state.yml was excluded or lost, leaving the linker without its bookkeeping.

node_modules built by a different tool

A previous step populated node_modules without Yarn, so no state file exists.

How to fix it

Re-run the install to regenerate state

A fresh install rebuilds node_modules and its state file together.

yarn install --immutable

Cache the state file with node_modules

Ensure the cache key covers .yarn-state.yml so restores are consistent.

1. Include node_modules/.yarn-state.yml in the cached paths.
2. Prefer caching ~/.yarn/cache and running yarn install over caching node_modules directly.
3. Invalidate the cache when the lockfile changes.

How to prevent it

• Cache the Yarn cache directory and run install, rather than caching node_modules.
• If caching node_modules, include .yarn-state.yml in the key.
• Use yarn install --immutable in CI for reproducible installs.

Related guides