How to fix npm ERR! code ELOOP npm ERR! ELOOP: too many symbolic links encountered in npm

npmINTERMEDIATEHIGHUpdated Dec 5, 2025· 181 views

ELOOP occurs when npm encounters a circular or excessively deep chain of symbolic links during package operations. Resolve it by removing node_modules, clearing cache, or using --no-bin-links flag.

Quick fix

Fixes ELOOP

# Clear npm cache
npm cache clean --force

# Remove node_modules directory
rm -rf node_modules

# On Windows PowerShell
Remove-Item -Recurse -Force node_modules

# Reinstall dependencies
npm install
  1. Clear npm cache and remove node_modules
  2. Verify no self-referencing symlinks exist
  3. Use --no-bin-links flag for network or problematic environments
  4. Configure npm to use local paths instead of network paths
npm — error
# Clear npm cache
npm cache clean --force
# Remove node_modules directory
rm -rf node_modules
# On Windows PowerShell
Remove-Item -Recurse -Force node_modules
# Reinstall dependencies
npm install
npm ERR! code ELOOP
npm ERR! ELOOP: too many symbolic links encountered

What this error means

The ELOOP error occurs when npm encounters a circular or excessively deep chain of symbolic links during package installation or operations. This happens when the filesystem traversal encounters the same directory multiple times through symlinks, creating an infinite loop. The error is triggered when a symlink points to itself (directly or indirectly) or when traversing network paths with thousands of subfolders exceeds the operating system's symlink depth limit of approximately 2000 levels.

Typical symptoms

  • npm install, npm update, or npm ci commands fail with 'ELOOP: too many symbolic links encountered' message
  • Error includes a path reference showing where the problematic symlink was detected
  • Issue occurs only when running npm commands, while the project directory itself is accessible
  • Global npm operations (npm install -g) fail on network drives but local installations work
  • Cordova, Ionic, or other tool-specific npm operations fail with ELOOP even though basic npm works

Common causes

  1. Self-referencing symlink in node_modules: A package folder contains a symlink that points to itself
  2. Network drive with excessive subfolders: User profile stored on network path with more than 2000+ nested subfolders
  3. Broken symlinks from previous installations that were not properly cleaned up
  4. Global npm cache on network path with deep folder hierarchies
  5. Circular dependency resolution: Package manager creates a symlink loop while resolving nested dependencies
  6. Workspace or monorepo symlink conflicts pointing back to parent directories

How to fix "npm ERR! code ELOOP npm ERR! ELOOP: too many symbolic links encountered"

1Clear npm cache and remove node_modules

Start fresh by clearing the npm cache and deleting the entire node_modules directory:

bash
# Clear npm cache
npm cache clean --force

# Remove node_modules directory
rm -rf node_modules

# On Windows PowerShell
Remove-Item -Recurse -Force node_modules

# Reinstall dependencies
npm install
2Verify no self-referencing symlinks exist

Check the node_modules directory for symlinks that point to themselves:

bash
# List all symlinks in node_modules
find node_modules -type l -exec ls -la {} \;

# On Windows PowerShell
Get-ChildItem -Path node_modules -Recurse -Attributes ReparsePoint

If you find a symlink pointing to itself, delete it manually and run npm install again.

3Use --no-bin-links flag for network or problematic environments

If you're on a network drive or experiencing persistent issues, try installing without creating binary symlinks:

bash
npm install --no-bin-links

# Or for global packages
npm install -g package-name --no-bin-links

This prevents npm from creating symlinks that may cause ELOOP errors on network filesystems.

4Configure npm to use local paths instead of network paths

If using npm on a network drive, configure npm cache and global prefix to use local filesystem paths:

bash
# Set local cache directory
npm config set cache ~/.npm-cache

# Set local global prefix
npm config set prefix ~/.npm-global

# On Windows, use local paths
npm config set cache C:\Users\YourUsername\AppData\Roaming\npm-cache --global

# Verify configuration
npm config list
5Delete package-lock.json and reinstall

If the issue persists, the lock file may be referencing broken symlinks:

bash
# Remove lock file and node_modules
rm -rf node_modules package-lock.json

# Clean cache again
npm cache clean --force

# Fresh install
npm install
6Use pnpm as an alternative package manager

If npm continues to fail, consider switching to pnpm which has better symlink handling:

bash
# Install pnpm globally
npm install -g pnpm

# Remove node_modules
rm -rf node_modules

# Install with pnpm
pnpm install

pnpm resolves packages to their real location rather than following symlink chains.

Advanced notes

The ELOOP error is particularly common in enterprise environments where user home directories are network-mounted. The operating system's symlink resolution has a depth limit (usually around 2000 levels), and traversing deeply nested network paths can exceed this. On Windows, the issue may be exacerbated by case-sensitivity differences and how NTFS handles junction points versus true symlinks. In CI/CD environments, consider using npm ci which respects lock files and may be less prone to symlink issues.

Frequently asked questions

What does "ELOOP" mean?
The ELOOP error occurs when npm encounters a circular or excessively deep chain of symbolic links during package installation or operations. This happens when the filesystem traversal encounters the same directory multiple times through symlinks, creating an infinite loop. The error is triggered when a symlink points to itself (directly or indirectly) or when traversing network paths with thousands of subfolders exceeds the operating system's symlink depth limit of approximately 2000 levels.
How do I fix "ELOOP"?
ELOOP occurs when npm encounters a circular or excessively deep chain of symbolic links during package operations. Resolve it by removing node_modules, clearing cache, or using --no-bin-links flag.
What causes "ELOOP"?
Self-referencing symlink in node_modules: A package folder contains a symlink that points to itself Network drive with excessive subfolders: User profile stored on network path with more than 2000+ nested subfolders Broken symlinks from previous installations that were not properly cleaned up
Is the "ELOOP" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading