npm link ELOOP "too many symbolic links" - Fix Circular Link in CI

ELOOP means the filesystem hit a symlink that points back through itself. With npm link it usually means a package was linked into its own node_modules, or two packages were linked into each other, creating a cycle the resolver cannot follow.

What this error means

A command that walks node_modules fails with ELOOP: too many symbolic links encountered at a path under a linked package. It follows npm link setups, especially when a package links itself or forms a link cycle.

Node output

Error: ELOOP: too many symbolic links encountered, stat
'/app/node_modules/my-lib/node_modules/my-lib'
    at Object.statSync (node:fs)
    code: 'ELOOP'

Common causes

A package linked into itself

Running npm link for a package and then linking it back into the same project can create a symlink whose target resolves to itself, producing a loop.

A cycle of linked packages

Two or more packages linked into each other form a circular symlink graph; the resolver loops until it hits ELOOP.

How to fix it

Remove the link cycle and reinstall

Unlink the offending packages and install from the registry/lockfile instead.

Terminal

npm unlink my-lib 2>/dev/null || true
rm -rf node_modules
npm ci

Avoid global links in CI

Use npm workspaces or a file: dependency for local cross-package references instead of npm link.
If you must link, never link a package into its own tree.
Start CI from a clean node_modules so no stale links survive.

How to prevent it

Prefer workspaces / file: deps over npm link in CI.
Never link a package into itself.
Install clean so leftover symlinks do not loop.