A recursive pnpm script (pnpm -r run <script>) failed in one of the workspace packages. RECURSIVE_RUN_FIRST_FAIL means pnpm stopped at the first package whose script exited non-zero - the real failure is that package’s task.
What this error means
pnpm -r run build (or test/lint) aborts with ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL, naming the package and exit code. The underlying error is the failing script in that package, printed above the pnpm wrapper.
pnpm output
@acme/api build: tsc -b
@acme/api build: Failed
/work: ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL Command "build" of "@acme/api" failed
with exit code 2
Diagnose it: which packages does the tool think exist?
Workspace failures are usually a globbing or topology problem: the tool cannot see a package, or it resolved a different dependency graph than you expect.
Terminal
# what the package manager sees
npm query ".workspace" 2>/dev/null || pnpm -r list --depth -1 || yarn workspaces list
# what the task runner will actually build, and in what order
npx turbo run build --dry-run=json | head -40
npx nx graph --file=graph.json
Common causes
A package script genuinely failed
The wrapper just surfaces that one package’s build/test/lint exited non-zero. The real error (a compile error, a failing test) is in that package’s output above.
Wrong topological order or missing build
A package that depends on another being built first can fail if the dependency was not built. --workspace-concurrency/topo order matters for build scripts.
How to fix it
Read and fix the failing package
Scroll up to the real error, then reproduce it for just that package.
Terminal
pnpm --filter @acme/api run build # reproduce the single failure
pnpm --filter @acme/api... run build # include its dependencies
Build in dependency order
Ensure dependencies build before dependents. pnpm respects the workspace graph; use filters to include upstream packages.
Terminal
pnpm -r --workspace-concurrency=1 run build
# or topo-aware with filtering
pnpm --filter "...[origin/main]" run build
How to prevent it
Treat RECURSIVE_RUN_FIRST_FAIL as a pointer to one package’s real error.
Run recursive scripts in dependency order so dependents see built upstreams.
Add per-package CI so a failing package is caught before the recursive run.
Frequently asked questions
What causes pnpm "ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL" in CI?
There are 2 common causes: a package script genuinely failed and wrong topological order or missing build. The wrapper just surfaces that one package’s build/test/lint exited non-zero.
How do I fix pnpm "ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL" in CI?
There are 2 fixes depending on which cause you have: read and fix the failing package and build in dependency order. Work through them in order, since the first is the most common.
What does pnpm "ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL" in CI actually mean?
pnpm -r run build (or test/lint) aborts with ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL, naming the package and exit code.
How do I stop pnpm "ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL" in CI happening again?
Treat RECURSIVE_RUN_FIRST_FAIL as a pointer to one package’s real error. The prevention section lists 3 changes that keep it from recurring.
