pnpm ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL in CI

By Daniel Zoghalchali·Latchkey

A pnpm -r (recursive) command ran a script across packages and one of them exited non-zero. pnpm reports the recursive failure; the real error is in that package log.

What this error means

pnpm -r build or test ends with "ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL" naming the package whose script failed, with that package output above.

pnpm

/workspace/packages/api build:
ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL  @acme/api@1.0.0 build:
`tsc -b` 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 failed

One package build or test exited non-zero; the recursive run surfaces it as the first failure.

Build order or missing dep

A package compiled before its dependency, or a missing dependency caused the script to fail.

Environment difference in CI

A script depends on a tool or env present locally but not on the runner.

How to fix it

Read the failing package log

Open the output of the named package and fix the real error.

Run that package in isolation

Filter to the failing package to iterate faster.

Terminal

pnpm --filter @acme/api build

How to prevent it

Build in topological order and keep package scripts environment-independent so a recursive run does not fail on the runner.

Frequently asked questions

What causes pnpm ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL in CI?

There are 3 common causes: a package script failed, build order or missing dep, and environment difference in ci. One package build or test exited non-zero; the recursive run surfaces it as the first failure.

How do I fix pnpm ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL in CI?

There are 2 fixes depending on which cause you have: read the failing package log and run that package in isolation. 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?