Node.js EPERM: operation not permitted

Resolve the Node.js EPERM error when writing, renaming, or deleting files on Windows and Linux due to locks, permissions, or antivirus interception.

beginnerdebuggingnodefilesystempermissions

Symptoms

Error: EPERM: operation not permitted, open/rename/unlink
npm install fails midway with EPERM on node_modules
fs.renameSync throws EPERM on Windows when the target exists

Possible causes

Another process (editor, antivirus, indexer) holds a handle on the file
The file or directory is not writable by the current user
On Windows, fs.rename over an existing file fails with EPERM instead of EEXIST
A read-only attribute or file lock from a crashed tool blocks the write

Diagnosis steps

Confirm the exact syscall and path from the error message

Interpretation

The trailing path tells you whether it is a lock, permission, or rename-over-existing problem.

On Windows, list processes holding the file with handle.exe or Resource Monitor

handle.exe node_modules\.cache

Interpretation

A live handle from an editor or antivirus explains EPERM even when permissions look correct.

Retry the operation while the suspect process is closed

Interpretation

If the error vanishes with the process closed, it was a handle lock rather than ACLs.

Root cause

EPERM means the operating system refused an operation the process had permission to attempt. On Windows the most common source is a lingering file handle or the fact that renaming over an existing file is treated as a permission error; on Linux it is a permissions or immutable-attribute problem on the path.

Fix

Release the handle by closing editors and pausing antivirus scans, then retry. Avoid rename-over-existing by unlinking first or using fs.promises.rename with a retry. Fix ACLs with chmod/chown or run from a directory the user owns; on Windows clear the read-only attribute.

Verify the fix

Re-run the failing install or script. No EPERM is printed and the target file or directory is created, renamed, or removed as expected.

Symptoms

Writes, renames, or deletes fail with EPERM: operation not permitted while the same path works from another shell. Intermittent failures point at a competing process rather than a permanent ACL problem.

Diagnosis

Read the full error line: it names the syscall (open, rename, unlink) and the path. On Windows, check for open handles with handle.exe or Resource Monitor, and on Linux check the mode and attributes:

ls -l path/to/file && lsattr path/to/file

Fix

Close the process holding the handle, pause antivirus, and retry. Never rename over an existing file on Windows; unlink first:

await fs.promises.rm(target, { force: true });
await fs.promises.rename(source, target);

If permissions are wrong, correct ownership with chown/chmod.

Verification

Re-run the original command and confirm the file operation completes without EPERM. Repeat a few times to rule out intermittent handle locks.