npm "ENOTEMPTY: rename" install race in CI

npm installs into staging directories and renames them into place. ENOTEMPTY on rename means the target already had content - a concurrent install or a stale partial directory collided.

What this error means

Install fails intermittently with "ENOTEMPTY: directory not empty, rename" pointing at a node_modules path. It clears on retry, which is the signature of a race rather than a real conflict.

node

npm error code ENOTEMPTY
npm error syscall rename
npm error ENOTEMPTY: directory not empty, rename
'/work/repo/node_modules/.foo-XXXX' -> '/work/repo/node_modules/foo'

Common causes

Concurrent installs sharing a tree

Two npm processes (e.g. parallel matrix jobs on one workspace, or a postinstall re-entering npm) write into the same node_modules.

A stale partial directory from a killed install

A previous install was interrupted, leaving a non-empty staging directory that the rename cannot overwrite.

How to fix it

Serialize installs and start clean

Ensure only one install touches a given node_modules, and remove leftovers before installing.

Terminal

rm -rf node_modules
npm ci

Avoid shared workspaces between parallel jobs

Give each parallel job its own checkout/cache so installs never collide.

Do not run two installs against the same directory at once.
Use per-job caches keyed by the lockfile hash.
Clear partial node_modules in a pre-install step.

How to prevent it

Run one install per node_modules tree.
Start from a clean node_modules with npm ci.
Latchkey self-healing managed runners auto-retry transient ENOTEMPTY install races and isolate per-job workspaces so concurrent installs do not collide.