NPM Error Troubleshooting: 15 Common Issues Fixed

Why NPM Errors Are So Frustrating

If you have spent any time with Node.js, you have run into npm errors. The cryptic error messages, the dependency hell, and the seemingly random breakages can waste hours of your time. This guide documents the 15 most common npm errors with proven, copy-paste solutions. Each error includes the full error message you will see, why it happens, and multiple ways to fix it for good.

Error 1: EACCES — Permission Denied

What You See

npm ERR! Error: EACCES: permission denied, access '/usr/local/lib/node_modules'
npm ERR! code EACCES
npm ERR! syscall access

Why It Happens

NPM is trying to install global packages in a directory owned by root. This happens when Node.js was installed using sudo or from a system package manager without proper permissions.

Solution 1: Use nvm (Recommended)

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Restart terminal, then install Node
nvm install --lts
nvm use --lts

# Now npm install -g works without sudo
npm install -g nodemon

Solution 2: Change npm global directory

# Create a directory for global packages
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to your ~/.bashrc or ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

# Reload your shell
source ~/.bashrc

Solution 3: Fix ownership (Linux/macOS)

# Change ownership of the npm directories
sudo chown -R $(whoami) /usr/local/lib/node_modules
sudo chown -R $(whoami) /usr/local/bin
sudo chown -R $(whoami) /usr/local/share

# NEVER use sudo with npm install
# BAD:  sudo npm install -g something
# GOOD: npm install -g something

Error 2: ERESOLVE — Dependency Conflicts

What You See

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: react@18.3.1
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from some-old-package@2.0.0

Why It Happens

A package you are installing requires a different version of a dependency than what your project already has. For example, some-old-package needs React 17 but your project uses React 18. npm 7+ enforces strict peer dependency resolution by default.

Solution 1: Use --legacy-peer-deps (Safe)

# Skip peer dependency checks (like npm 6 behavior)
npm install --legacy-peer-deps

# Make it permanent in .npmrc
echo "legacy-peer-deps=true" >> .npmrc

Solution 2: Use --force (Last resort)

# Force install — may break things
npm install --force

# This ignores all warnings and conflicts
# Only use when you are sure the packages are compatible

Solution 3: Fix the actual conflict

# See the full dependency tree
npm ls react

# Find which package needs the old version
npm explain react

# Update the problematic package
npm install some-old-package@latest

# Or add overrides in package.json (npm 8.3+)
# In package.json:
# "overrides": {
#   "some-old-package": {
#     "react": "$react"
#   }
# }

Error 3: ENOENT — No Such File or Directory

What You See

npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path /Users/you/project/package.json
npm ERR! errno -2
npm ERR! enoent ENOENT: no such file or directory, open 'package.json'

Why It Happens

You are running npm install in a directory without a package.json, or your node_modules is corrupted and referencing files that no longer exist.

Solutions

# If package.json is missing — initialize a new project
npm init -y

# If node_modules is corrupted — clean reinstall
rm -rf node_modules
rm -f package-lock.json
npm install

# On Windows (PowerShell)
Remove-Item -Recurse -Force node_modules
Remove-Item -Force package-lock.json
npm install

# If npm cache is corrupted
npm cache clean --force
npm install

Error 4: MODULE_NOT_FOUND

What You See

Error: Cannot find module 'express'
Require stack:
- /Users/you/project/server.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1048:15)
    at Module._load (node:internal/modules/cjs/loader:901:27)
    code: 'MODULE_NOT_FOUND'

Why It Happens

The module is not installed, was installed globally instead of locally, node_modules was deleted, or there is a casing mismatch in the import path.

Solutions

# 1. Install the missing module
npm install express

# 2. Clear cache and reinstall everything
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

# 3. Check if the module is in package.json
cat package.json | grep express

# 4. Verify import casing (especially on Linux)
# Wrong: require('Express')
# Right: require('express')

# 5. Check node_modules exists and has the package
ls node_modules/express

Error 5: EPERM — Operation Not Permitted (Windows)

What You See

npm ERR! code EPERM
npm ERR! syscall unlink
npm ERR! path C:Usersyouproject
ode_modules.package-lock.json
npm ERR! errno -4048
npm ERR! Error: EPERM: operation not permitted, unlink

Why It Happens

On Windows, another process (editor, antivirus, or the running application) has locked files inside node_modules, preventing npm from modifying them.

Solutions

# 1. Close your editor and any running Node processes
taskkill /f /im node.exe

# 2. Close VS Code or other editors that watch node_modules

# 3. Delete node_modules using an elevated prompt
# Open PowerShell as Administrator
Remove-Item -Recurse -Force node_modules
npm install

# 4. Disable Windows antivirus for project folder temporarily

# 5. Add node_modules to antivirus exclusions permanently
# Windows Defender: Settings > Virus Protection > Exclusions
# Add: C:Usersyouproject
ode_modules

# 6. Use npm cache to fix corrupted state
npm cache clean --force
npm install

Error 6: npm audit — Security Vulnerabilities

What You See

found 12 vulnerabilities (3 low, 5 moderate, 3 high, 1 critical)
  run `npm audit fix` to fix them, or `npm audit` for details

Solutions

# Auto-fix what can be safely fixed
npm audit fix

# Force fix (may include breaking changes)
npm audit fix --force

# See detailed vulnerability report
npm audit

# Fix a specific package
npm audit fix --package-name lodash

# If you cannot fix (e.g., dev dependency)
# Add to package.json to suppress warnings:
# "overrides": {
#   "vulnerable-package": ">=fixed-version"
# }

# Generate a full audit report
npm audit --json > audit-report.json

Error 7: ERR_SOCKET_TIMEOUT

What You See

npm ERR! code ERR_SOCKET_TIMEOUT
npm ERR! network request to https://registry.npmjs.org/package failed
npm ERR! network This is a problem related to network connectivity.

Solutions

# 1. Increase timeout
npm config set fetch-timeout 60000
npm config set fetch-retries 5

# 2. Switch registry (use a mirror)
npm config set registry https://registry.npmmirror.com/

# 3. Check proxy settings
npm config get proxy
npm config get https-proxy

# Remove if not needed
npm config delete proxy
npm config delete https-proxy

# Set if behind a corporate proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# 4. Clear DNS cache
# Windows: ipconfig /flushdns
# macOS: sudo dscacheutil -flushcache

# 5. Reset registry to default
npm config set registry https://registry.npmjs.org/

Error 8: EINTEGRITY — Checksum Failed

What You See

npm ERR! code EINTEGRITY
npm ERR! sha512-abc123... integrity checksum failed
npm ERR! Wanted: sha512-abc123...
npm ERR! Found: sha512-xyz789...

Why It Happens

The downloaded package does not match the checksum in package-lock.json. This usually means a corrupted cache, a man-in-the-middle proxy, or a registry issue.

Solutions

# 1. Clean cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

# 2. Verify cache integrity
npm cache verify

# 3. If behind a corporate proxy, it may be intercepting
# Try with strict-ssl disabled (temporarily!)
npm config set strict-ssl false
npm install
npm config set strict-ssl true  # Re-enable!

Error 9: E404 — Package Not Found

What You See

npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/@myorg/mypackage
npm ERR! 404 '@myorg/mypackage@latest' is not in this registry.

Solutions

# 1. Check the package name is correct
npm search package-name

# 2. For scoped packages, check registry configuration
# .npmrc
@myorg:registry=https://npm.pkg.github.com/

# 3. Authenticate for private packages
npm login --registry=https://npm.pkg.github.com/ --scope=@myorg

# 4. Check if the package was unpublished
npm view package-name versions

# 5. Verify .npmrc is correct
cat .npmrc

Error 10: gyp ERR! — Native Module Build Failed

What You See

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! not ok
npm ERR! code 1
npm ERR! path /project/node_modules/bcrypt

Why It Happens

Some npm packages include native C/C++ addons that need to be compiled. This requires Python, a C++ compiler, and node-gyp. Windows is especially tricky because these tools are not installed by default.

Solutions

# Windows — Install build tools (run as Administrator)
npm install -g windows-build-tools
# Or install Visual Studio Build Tools manually from:
# https://visualstudio.microsoft.com/visual-cpp-build-tools/

# Windows — Install Python 3.x and add to PATH
# Then set python path for node-gyp
npm config set python python3

# macOS — Install Xcode Command Line Tools
xcode-select --install

# Linux (Ubuntu/Debian) — Install build essentials
sudo apt-get install -y build-essential python3

# For specific packages, use prebuilt binaries
# Instead of bcrypt, use bcryptjs (pure JavaScript)
npm install bcryptjs  # Drop-in replacement, no compilation

# Rebuild native modules after Node version change
npm rebuild
# Or rebuild a specific package
npm rebuild bcrypt

Error 11: ENOMEM — Out of Memory

What You See

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
npm ERR! code ENOMEM

Solutions

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
npm install

# Or for a specific npm command
NODE_OPTIONS="--max-old-space-size=4096" npm run build

# Windows PowerShell
$env:NODE_OPTIONS="--max-old-space-size=4096"
npm run build

# Permanently add to your shell profile
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.bashrc

Error 12: npm WARN deprecated

What You See

npm WARN deprecated uuid@3.4.0: Please upgrade to version 7 or higher.
npm WARN deprecated request@2.88.2: request has been deprecated

How to Handle

# These are warnings, not errors. Your install still works.
# To find which package uses the deprecated dependency:
npm ls uuid
npm ls request

# Update the parent package
npm update parent-package

# If the parent package is unmaintained, find an alternative
# or add an override:
# In package.json:
# "overrides": {
#   "uuid": "^9.0.0"
# }

Error 13: package-lock.json Conflicts

What You See

npm ERR! code EUSAGE
npm ERR!
npm ERR! `npm ci` can only install packages when your package.json and
npm ERR! package-lock.json are in sync.

Solutions

# 1. Regenerate the lock file
rm package-lock.json
npm install

# 2. During git merge conflicts in package-lock.json
# Accept either version, then regenerate
git checkout --theirs package-lock.json
npm install

# 3. Best practice: never manually edit package-lock.json
# Always use npm install/uninstall to make changes

# 4. In CI/CD, always use npm ci (clean install)
# It installs exact versions from package-lock.json
npm ci

Error 14: ELIFECYCLE — Script Failed

What You See

npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! my-app@1.0.0 build: `react-scripts build`
npm ERR! Exit status 1

Solutions

# 1. Read the actual error ABOVE the npm ERR lines
# The real error is usually printed before npm's error summary

# 2. Clean and rebuild
rm -rf node_modules package-lock.json
npm install
npm run build

# 3. Check if the script exists in package.json
cat package.json | grep -A 5 '"scripts"'

# 4. Run with verbose logging
npm run build --verbose 2>&1 | tee build.log

Error 15: ERR_OSSL_EVP_UNSUPPORTED (OpenSSL)

What You See

Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:67:19)
    code: 'ERR_OSSL_EVP_UNSUPPORTED'

Why It Happens

Node.js 17+ uses OpenSSL 3.0, which removed support for some older algorithms. Legacy tools like Webpack 4 and Create React App (older versions) use these algorithms.

Solutions

# Quick fix: set OpenSSL legacy provider
export NODE_OPTIONS=--openssl-legacy-provider
npm run build

# Windows PowerShell
$env:NODE_OPTIONS="--openssl-legacy-provider"
npm run build

# Permanent fix: update your build tools
npm install react-scripts@latest
# Or migrate from Webpack 4 to Webpack 5
npm install webpack@5 webpack-cli@5

# In package.json scripts (cross-platform)
"scripts": {
  "build": "react-scripts build",
  "build:legacy": "cross-env NODE_OPTIONS=--openssl-legacy-provider react-scripts build"
}

npm vs yarn vs pnpm Comparison

# Install pnpm
npm install -g pnpm

# Common pnpm commands
pnpm install            # Install all dependencies
pnpm add express        # Add a dependency
pnpm add -D vitest      # Add a dev dependency
pnpm remove lodash      # Remove a dependency
pnpm run build          # Run a script
pnpm store prune        # Clean unused packages from store

.npmrc Configuration

# Project-level .npmrc (place in project root)

# Use exact versions by default (no ^ or ~)
save-exact=true

# Set default registry
registry=https://registry.npmjs.org/

# Scoped registry for private packages
@mycompany:registry=https://npm.pkg.github.com/

# Auth token for private registry
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

# Engine strict mode (enforce Node version)
engine-strict=true

# Legacy peer deps mode
legacy-peer-deps=true

# Increase network timeout
fetch-timeout=60000
fetch-retries=3

Quick Reference — Error Fix Cheat Sheet

Nuclear Option — When Nothing Works

# The ultimate reset sequence:
# 1. Kill all Node processes
killall node 2>/dev/null || taskkill /f /im node.exe 2>nul

# 2. Clean everything
rm -rf node_modules
rm -f package-lock.json
npm cache clean --force

# 3. Clear npx cache
rm -rf ~/.npm/_npx

# 4. Verify npm is not broken
npm --version
node --version

# 5. Fresh install
npm install

# If npm itself is broken:
# Reinstall Node.js entirely via nvm
nvm install --lts --reinstall-packages-from=current
nvm use --lts