This error occurs when Node.js attempts a file system operation that the operating system denies due to insufficient permissions. It commonly happens during chmod, rename, unlink, or write operations, particularly on Windows with antivirus software or on Unix-like systems with incorrect file ownership.
The EPERM error code stands for "Error: PERMission denied" and indicates that the operating system prevented Node.js from completing a file system operation. When you use Node.js file system methods like fs.chmod(), fs.rename(), fs.unlink(), or fs.writeFile(), the underlying OS must grant permission for these operations. If the current user lacks sufficient privileges, the file is locked by another process, or security software blocks the operation, Node.js receives an EPERM error from the OS. This error is particularly common on Windows systems where antivirus software (especially Windows Defender with Tamper Protection) actively monitors and can block file operations in node_modules directories. On Unix-like systems (Linux, macOS), it typically occurs when attempting to modify files owned by another user or protected system files without proper permissions. Understanding the cross-platform differences is crucial: Windows has simpler permission models compared to Unix, and Node.js's chmod() has limited functionality on Windows since it only supports read/write permission changes.
Close your IDE (VS Code, WebStorm, etc.), any terminals running development servers, and any file explorers viewing the project directory:
# Stop any running Node processes
# On Windows Task Manager: End all node.exe processes
# On macOS/Linux:
pkill -f node
# Then reopen a fresh terminal and retry the operationFile locks are a common cause of EPERM errors. Even hidden background processes can hold locks on files in node_modules, preventing modifications.
If the error occurs during npm operations or when modifying system-level files, run with elevated privileges.
On Windows:
- Right-click Command Prompt or PowerShell
- Select "Run as administrator"
- Navigate to your project directory and retry the operation
On macOS/Linux:
# Use sudo for the specific operation that failed
sudo npm install
# Or change ownership of the project directory
sudo chown -R $USER:$USER /path/to/projectAvoid using sudo for regular npm operations when possible. If you frequently need sudo, your npm configuration may need adjustment to use a user-owned directory for global packages.
Antivirus software, particularly Windows Defender, commonly blocks file operations in node_modules.
Windows Defender exclusions:
1. Open Windows Security > Virus & threat protection
2. Click "Manage settings" under Virus & threat protection settings
3. Scroll to "Exclusions" and click "Add or remove exclusions"
4. Add your project folder (e.g., C:\Users\YourName\projects)
Disable Tamper Protection temporarily:
1. Windows Security > Virus & threat protection
2. Manage settings > Tamper Protection > Toggle off
3. Retry the operation, then re-enable Tamper Protection
For other antivirus software, add the project directory or node_modules to the exclusion/whitelist in the antivirus settings. This is safe for development projects you trust.
Ensure the target file or directory is not marked as read-only.
On Windows (Command Prompt):
# Remove read-only attribute from a specific file
attrib -r "path\to\file"
# Remove read-only recursively from directory
attrib -r "path\to\directory\*" /s /dOn macOS/Linux:
# Check current permissions
ls -la /path/to/file
# Make file writable by owner
chmod u+w /path/to/file
# Make entire directory tree writable
chmod -R u+w /path/to/directoryAfter removing read-only status, retry the operation that caused the EPERM error.
If the error occurs during npm operations, do a complete clean reinstall. Windows directory locking may require retry logic.
On macOS/Linux:
rm -rf node_modules
rm -f package-lock.json
npm cache clean --force
npm installOn Windows (PowerShell, may need multiple attempts):
# First attempt - close all programs first
Remove-Item -Recurse -Force node_modules -ErrorAction SilentlyContinue
# If locked, wait and retry
Start-Sleep -Seconds 2
Remove-Item -Recurse -Force node_modules -ErrorAction SilentlyContinue
# Then proceed
Remove-Item package-lock.json -ErrorAction SilentlyContinue
npm cache clean --force
npm installConsider using graceful-fs or rimraf packages in build scripts for more reliable cross-platform file operations with automatic retry logic.
Cross-platform Node.js permission differences: Node.js does not fully support Windows permissions. The fs.chmod() method only works reliably on Unix systems. On Windows, fs.chmod() can only toggle read/write permission and does not distinguish between user, group, or others. For truly cross-platform code, avoid relying on chmod() and instead use higher-level abstractions or platform-specific checks.
Graceful file operations: For production code that needs to handle file system operations robustly, use the graceful-fs library, which wraps fs methods with queuing and retry logic. The rimraf package also provides cross-platform recursive deletion with retry mechanisms for locked directories on Windows.
Docker and containerization: Inside Docker containers on Windows using WSL2 or Hyper-V, permission issues can occur when bind-mounting volumes. Use named volumes for node_modules instead of bind mounts: docker run -v /app/node_modules myapp. This avoids permission conflicts between host and container file systems.
CI/CD environments: In CI pipelines (GitHub Actions, Jenkins), EPERM errors can occur due to previous build artifacts being locked. Always use fresh environments or add cleanup steps with retry logic before builds. GitHub Actions' actions/cache can sometimes preserve locked files between runs.
File locking on Windows: Windows file locking behavior differs from Unix. A file can remain locked for milliseconds after a process closes it. Use retry logic with maxRetries option in fs.rm() or packages like retry-fs for operations that might hit transient locks.
Monorepo considerations: In monorepos with multiple packages, cross-package file operations during build steps may hit EPERM errors if builds run concurrently. Use build orchestration tools (Turborepo, Nx) that properly sequence operations and avoid file conflicts.
Error: EMFILE: too many open files, watch
EMFILE: fs.watch() limit exceeded
Error: Middleware next() called multiple times (next() invoked twice)
Express middleware next() called multiple times
Error: Worker failed to initialize (worker startup error)
Worker failed to initialize in Node.js
Error: EMFILE: too many open files, open 'file.txt'
EMFILE: too many open files
Error: cluster.fork() failed (cannot create child process)
cluster.fork() failed - Cannot create child process