How to fix npm ERR! code EMLINK npm ERR! EMLINK: too many links in npm

npmINTERMEDIATEMEDIUMUpdated Dec 5, 2025· 135 views

The EMLINK error occurs when npm encounters too many hard links or symlinks during installation, typically caused by filesystem limits, self-referencing symlinks, or link configuration issues. Clear your cache, check for broken symlinks, and reconfigure npm's linking behavior to resolve the problem.

Quick fix

Fixes EMLINK

npm cache clean --force
rm -rf node_modules
rm -f package-lock.json
  1. Clear the npm cache and remove node_modules
  2. Check for self-referencing symlinks
  3. Disable npm symlink creation if on network drives
  4. Reinstall dependencies fresh
npm — error
npm cache clean --force
rm -rf node_modules
rm -f package-lock.json
npm ERR! code EMLINK
npm ERR! EMLINK: too many links

What this error means

EMLINK stands for "Error Maximum LINK" and is a filesystem-level error indicating that the system has hit its maximum limit for hard links or symbolic links. During npm install, npm creates symlinks to bin files and dependencies in node_modules. When the filesystem encounters too many of these links—either from accumulated installations, self-referencing symlinks, or corrupted link chains—npm cannot complete the installation. This is distinct from ELOOP (too many symbolic link levels), though both involve linking issues. The error can also occur when npm tries to create subdirectories and the system refuses due to existing link counts exceeding the filesystem's limit.

Typical symptoms

  • npm install fails with EMLINK error during dependency resolution
  • Error message includes 'too many links' alongside a file path in node_modules
  • Installation works on some machines but fails on others (especially network drives or shared filesystems)
  • Clean installations fail but subsequent attempts work (suggesting cache corruption)
  • Global npm installs fail while local installs work (or vice versa)
  • Docker builds fail at the npm install layer with EMLINK errors

Common causes

  1. Self-referencing or circular symlinks in node_modules where a package links to itself
  2. Accumulated symlinks from multiple npm installations without proper cleanup
  3. Corrupted or incomplete previous npm installs leaving broken symlinks behind
  4. npm cache corruption containing invalid link references
  5. File systems with hard link limits (some network drives and shared storage have lower limits)
  6. Local file dependencies in package.json creating symlinks that nest too deeply

How to fix "npm ERR! code EMLINK npm ERR! EMLINK: too many links"

1Clear the npm cache and remove node_modules

Start with a clean slate by removing cached data and installed modules. This eliminates corruption from previous failed installs.

bash
npm cache clean --force
rm -rf node_modules
rm -f package-lock.json

On Windows, use these commands instead:

bash
npm cache clean --force
rmdir /s /q node_modules
del package-lock.json
2Check for self-referencing symlinks

Before reinstalling, verify there are no broken symlinks. Look for symlinks that point to themselves or create circular references.

On macOS/Linux:

bash
find . -type l -exec sh -c 'file "$1" | grep -q "broken" && echo "$1"' _ {} \;

This shows all broken symlinks. Remove any found in your project directory:

bash
rm -f path/to/broken/symlink

On Windows, use a file explorer tool or PowerShell to inspect junction/symlink targets.

3Disable npm symlink creation if on network drives

Network filesystems and shared storage often have lower hard link limits. Configure npm to copy dependencies instead of symlinking them.

Create or edit .npmrc in your project root:

bash
install-links=false

Or run npm install with the flag:

bash
npm install --install-links=false

Note: This applies to npm v9+. For older versions, use --no-bin-links (though this only affects binary links, not all symlinks).

4Reinstall dependencies fresh

Now that you've cleaned up, reinstall with a verbose flag to see exactly where the error occurs if it happens again.

bash
npm install --verbose

If the error persists, the output will show the exact package/path causing the issue. Note this for the next step.

5For persistent issues, check local file dependencies

If you use local file references in package.json (e.g., "dependency": "file:../local-package"), these create symlinks that can hit limits. Convert them to copies instead:

In package.json, change:

json
"mypackage": "file:../mypackage"

To use npm pack instead:

bash
cd ../mypackage
npm pack
cd ../myapp
npm install ../mypackage/mypackage-1.0.0.tgz

This creates a tarball copy instead of a symlink, avoiding link limit issues.

Advanced notes

The EMLINK error is filesystem-specific and behavior varies by OS and storage type. On Linux systems with ext4, the hard link limit is typically 65,000 per inode. Network File System (NFS) mounts and Windows SMB shares often have stricter limits. If you're on a network drive and repeatedly encounter EMLINK, permanently configure install-links=false in your global .npmrc (~/.npmrc on Unix, %APPDATA%\.npmrc on Windows). For monorepo workspaces, consider using npm workspaces (npm v7+) or yarn/pnpm, which handle symlinks more intelligently. If the error occurs only in CI/CD pipelines, check if the runner's filesystem or Docker image has different link limit configurations than your local machine.

Frequently asked questions

What does "EMLINK" mean?
EMLINK stands for "Error Maximum LINK" and is a filesystem-level error indicating that the system has hit its maximum limit for hard links or symbolic links. During npm install, npm creates symlinks to bin files and dependencies in node_modules. When the filesystem encounters too many of these links—either from accumulated installations, self-referencing symlinks, or corrupted link chains—npm cannot complete the installation.
How do I fix "EMLINK"?
The EMLINK error occurs when npm encounters too many hard links or symlinks during installation, typically caused by filesystem limits, self-referencing symlinks, or link configuration issues. Clear your cache, check for broken symlinks, and reconfigure npm's linking behavior to resolve the problem.
What causes "EMLINK"?
Self-referencing or circular symlinks in node_modules where a package links to itself Accumulated symlinks from multiple npm installations without proper cleanup Corrupted or incomplete previous npm installs leaving broken symlinks behind
Is the "EMLINK" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading