Yarn Berry zero-installs failing (.yarn/cache not committed) in CI

Zero-installs means committing .yarn/cache and .pnp.cjs so CI needs no network install. If those paths are gitignored, the immutable install has nothing to resolve against and fails, defeating the whole scheme.

What this error means

yarn install in CI reports missing archives or an absent .pnp.cjs, and inspecting the repo shows .yarn/cache is not tracked because a default .gitignore excluded it.

yarn

Internal Error: EACCES / ENOENT: no such file or directory, open '.pnp.cjs'
    at ... (the PnP runtime was expected but not committed)

Common causes

The .yarn/cache and .pnp.cjs are gitignored

A generic Node .gitignore excludes .yarn/cache and .pnp.*, so the zero-install artifacts never reach CI.

Zero-installs assumed without committing artifacts

CI has no yarn install --immutable producing artifacts, and none are committed, so resolution has no source.

How to fix it

Commit the zero-install artifacts

Adjust .gitignore to keep .yarn/cache and .pnp.cjs while ignoring .yarn/install-state.gz.
Commit those artifacts.
CI then runs yarn install --immutable with everything present.

.gitignore

# .gitignore
.yarn/*
!.yarn/cache
!.yarn/patches
!.yarn/plugins
!.yarn/releases
.pnp.*
!.pnp.cjs

Or opt out of zero-installs and cache in CI

If you prefer not to commit the cache, cache .yarn/cache in CI and run a normal immutable install.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: .yarn/cache
    key: yarn-${{ hashFiles('yarn.lock') }}

How to prevent it

Decide between zero-installs (commit the cache) and CI caching, and configure .gitignore to match.
Never leave .yarn/cache half-committed.
Keep .pnp.cjs committed when relying on zero-installs.