Yarn classic "--frozen-lockfile" mismatch in CI

By Kaveh Alemi·Latchkey

Yarn 1 with --frozen-lockfile refuses to modify yarn.lock. When resolution would change the lockfile, it stops and tells you the lockfile needs updating, keeping CI reproducible.

What this error means

yarn install --frozen-lockfile fails with "error Your lockfile needs to be updated, but yarn was run with --frozen-lockfile."

error Your lockfile needs to be updated, but yarn was run with `--frozen-lockfile`.
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.

Common causes

package.json changed without relocking

A dependency was edited but yarn.lock was not regenerated, so a frozen install would need to change it.

The lockfile was not committed

A local install updated yarn.lock but the change was not committed, leaving CI with a stale lock.

How to fix it

Regenerate and commit yarn.lock

1. Run yarn install locally to update the lockfile.
2. Commit yarn.lock with the manifest change.
3. Push so the frozen install matches.

yarn install
git add yarn.lock package.json

Keep --frozen-lockfile in CI

Run installs frozen in CI so drift fails fast rather than silently rewriting the lock.

- run: yarn install --frozen-lockfile

How to prevent it

• Commit yarn.lock in the same commit as any dependency change.
• Keep --frozen-lockfile on in CI.
• Resolve lock conflicts by re-running yarn install.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation