npm "EPERM: operation not permitted, rename" - Fix Staging Rename in CI

By Kaveh Alemi·Latchkey

npm stages a package then renames it into node_modules. An EPERM specifically on that rename means the OS refused the move - the target is locked, read-only, owned by another user, or held open by another process.

What this error means

npm fails with EPERM: operation not permitted, rename on a .staging/<pkg> path. It is common on Docker with root-owned node_modules, on read-only mounts, or when a file watcher/antivirus holds the file.

npm error code EPERM
npm error syscall rename
npm error path /app/node_modules/.staging/esbuild-XXXX
npm error dest /app/node_modules/esbuild
npm error Error: EPERM: operation not permitted, rename '...' -> '...'

Common causes

Root-owned or read-only node_modules

A node_modules created by root (or on a read-only mount) cannot be modified by the non-root build user, so the staging rename is denied.

A process holding the file open

A watcher, parallel step, or antivirus with a handle on the destination blocks the rename until released.

How to fix it

Fix ownership and reinstall clean

Hand node_modules back to the build user and reinstall on a writable path.

sudo chown -R "$(id -u):$(id -g)" node_modules 2>/dev/null || true
rm -rf node_modules
npm ci

Remove locks and read-only mounts

1. Ensure no watcher/antivirus holds files under node_modules during install.
2. Install on a writable layer, not a read-only volume.
3. Run npm as the user that owns the workspace.

How to prevent it

• Keep node_modules owned by the build user.
• Install on writable layers only.
• Avoid concurrent processes holding module files.

Frequently asked questions

Related guides

References

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