Fix 'EPERM: operation not permitted, rename' Error in Node.js on Windows

The Error

Error: EPERM: operation not permitted, rename 'C:\project\file.tmp' -> 'C:\project\file.js'

Node.js tried to rename a file. Windows said no. That's the short version.

The longer version: something else had a lock on the file — a background scanner, a zombie process, or your own code that forgot to close a stream first. This error shows up most often during builds, npm install, or any tool that writes via temp-file-then-rename (webpack, rollup, esbuild, fs-extra, and friends all do this).

Root Cause

Windows uses mandatory file locking. On Linux, you can rename an open file without issue. On Windows, you cannot — any process holding the file open blocks the rename until it lets go. The usual suspects:

Antivirus / Windows Defender — scans the file the moment it lands on disk, right as Node tries to rename it
Another Node process — a watcher, dev server, or zombie process still holding the handle
Windows Search indexer — quietly scanning your project folder in the background
Your own code — calling fs.rename before the write stream has fully closed
Insufficient permissions — Node running without write access to the target directory

Fix 1: Exclude the Project Folder from Antivirus (Most Common Fix)

In most cases, Windows Defender is the culprit. It scans new files the instant they hit disk — exactly when Node is trying to rename them. The window is tiny (often under 50ms), but it's enough to trigger EPERM.

Add your project folder to the exclusion list:

Open Windows Security → Virus & threat protection → Manage settings
Scroll to Exclusions → Add or remove exclusions
Add a Folder exclusion for your project root (e.g., C:\projects\myapp)
Also exclude node_modules and any dist / build directories if they're outside the project root

Third-party antivirus tools (Kaspersky, Bitdefender, etc.) have the same setting under real-time protection exclusions.

Fix 2: Kill Zombie Node Processes

A crashed dev server doesn't always clean up after itself. The process is gone from Task Manager, but Windows still has its file handles marked as in use. Kill everything and start fresh:

taskkill /F /IM node.exe

Need to be more surgical? PowerShell lets you pick which processes to stop:

Get-Process node | Stop-Process -Force

Once the slate is clean, re-run your build or install command.

Fix 3: Retry Logic in Your Own Code

Locks from Defender or the indexer typically clear in under 200ms. Rather than crashing hard, retry with exponential backoff — double the delay each attempt, so you're not hammering a file that's still locked:

const fs = require('fs');

function renameWithRetry(oldPath, newPath, retries = 5, delay = 100) {
  return new Promise((resolve, reject) => {
    fs.rename(oldPath, newPath, (err) => {
      if (!err) return resolve();
      if (err.code === 'EPERM' && retries > 0) {
        setTimeout(() => {
          renameWithRetry(oldPath, newPath, retries - 1, delay * 2)
            .then(resolve)
            .catch(reject);
        }, delay);
      } else {
        reject(err);
      }
    });
  });
}

// Usage
await renameWithRetry('output.tmp', 'output.js');

With 5 retries and 100ms initial delay, you get up to ~3.1 seconds of total wait time before giving up — more than enough for a transient scanner lock.

Fix 4: Disable Windows Search Indexing for Project Folders

The Search indexer is a quieter culprit but causes the same EPERM on heavy write operations like npm install into a large monorepo:

Open File Explorer → right-click the project folder → Properties
On the General tab, click Advanced
Uncheck Allow files in this folder to have contents indexed
Apply to all subfolders when prompted

Fix 5: Run with Elevated Permissions (Last Resort)

Writing to a protected path like C:\Program Files or a system-owned directory? Node needs Administrator rights:

# Run Command Prompt as Administrator, then:
node build.js

For npm scripts, right-click the terminal and choose "Run as administrator". Treat this as a last resort — if the target folder is one you created yourself, fix the root cause instead of escalating privileges.

Fix 6: Ensure the File Is Closed Before Renaming

If your own code caused the lock, the fix is simple: wait for the stream to fully close before calling rename. The end callback is your signal:

const fs = require('fs');

const stream = fs.createWriteStream('output.tmp');
stream.write('hello world');
stream.end(() => {
  // File handle is released here — safe to rename
  fs.rename('output.tmp', 'output.js', (err) => {
    if (err) console.error('Rename failed:', err);
  });
});

Calling fs.rename inside the end callback guarantees the handle is gone before the rename attempt.

Verify the Fix

Run the failing command again to confirm it's resolved:

# Re-run the failing command
npm run build

# Or test a rename directly
node -e "require('fs').renameSync('test.tmp', 'test.out'); console.log('OK')"

If the original error came from npm install, wipe node_modules and the lock file before retrying — a partial install can leave stale handles:

rd /s /q node_modules
del package-lock.json
npm install

Prevention

Exclude project folders from antivirus on day one — don't wait for the error to appear. It's standard practice on Windows dev machines and takes 30 seconds to set up.
Use a process manager like PM2 for long-running servers — it properly closes file handles on restart rather than hard-killing the process and leaving orphaned locks.
Write temp files to os.tmpdir() when possible — system temp directories are usually excluded from scanners by default, so rename collisions are rare.
Build retry logic into production scripts — Windows CI servers and shared network drives are especially prone to transient locks. A 3-retry loop costs nothing and prevents random build failures.

If your project also runs on Linux and you're juggling file permissions across both platforms, the Unix Permissions Calculator on ToolCraft lets you work out the right chmod values visually — no octal memorization needed.