Node.js EPERM

What It Means

EPERM stands for “Error: Operation Not PERMitted.” This error occurs when the operating system denies an operation, even if the file permissions would otherwise allow it. This differs from EACCES — EPERM typically involves system-level restrictions, file locks, or operations that require elevated privileges.

Common Causes

• Trying to modify a file that is locked by another process
• Attempting to delete or modify a read-only file system
• Windows: file locked by antivirus or another application
• Modifying files inside node_modules while npm is running
• Insufficient OS-level privileges for the operation
• Trying to write to a mounted read-only volume
• Docker volume permission issues

How to Fix

Fix on Windows (most common)

# Close any editors or processes using the files
# Then retry the operation

# Clear npm cache
npm cache clean --force

# Delete node_modules manually
rd /s /q node_modules
# Then reinstall
npm install

# Run as administrator if needed
# Right-click terminal -> "Run as Administrator"

Fix file lock issues

const fs = require('fs');

// Retry on EPERM with a delay
async function writeFileWithRetry(path, data, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      fs.writeFileSync(path, data);
      return;
    } catch (error) {
      if (error.code === 'EPERM' && i < retries - 1) {
        await new Promise(r => setTimeout(r, 1000));
        continue;
      }
      throw error;
    }
  }
}

Fix npm EPERM

# Fix npm permissions (Linux/macOS)
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Or configure npm to use a different directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Fix in Docker

# Run as non-root with proper permissions
FROM node:20-alpine

RUN addgroup -S appgroup && adduser -S appuser -G appgroup

WORKDIR /app
COPY --chown=appuser:appgroup . .

RUN npm ci

USER appuser
CMD ["node", "app.js"]

Handle EPERM gracefully

const fs = require('fs/promises');

async function safeDelete(filePath) {
  try {
    await fs.unlink(filePath);
  } catch (error) {
    if (error.code === 'EPERM') {
      // Try to remove read-only flag first
      try {
        await fs.chmod(filePath, 0o666);
        await fs.unlink(filePath);
      } catch (innerError) {
        console.error(`Cannot delete ${filePath}: file may be locked`);
        throw innerError;
      }
    } else {
      throw error;
    }
  }
}

Fix Linux/macOS permissions

# Check current permissions
ls -la /path/to/file

# Fix ownership
sudo chown -R $USER:$USER /path/to/directory

# Check for immutable flags (Linux)
lsattr /path/to/file
# Remove immutable flag
sudo chattr -i /path/to/file

# Check mount options
mount | grep "read-only"

Related Errors

• Node.js EACCES - Access denied: permission-based denial (different from system-level denial).
• Node.js ENOENT - File doesn’t exist at all.