npm "Tracker idealTree already exists" - Fix Concurrent Install Error

By Kaveh Alemi·Latchkey

npm builds an in-memory "idealTree" while installing and guards it so only one install runs at a time. This error means a second npm started while another was still going, or a previous one died without cleaning up.

What this error means

An install fails almost immediately with "Tracker "idealTree" already exists". It often shows up when a build script kicks off two installs in parallel, or after a cancelled job left npm in a bad state.

npm output

npm error Tracker "idealTree" already exists
npm error A complete log of this run can be found in: .../_logs/...-debug-0.log

Diagnose it: reproduce the CI install locally

Install failures are usually environment drift rather than a broken lockfile: a different package-manager major, a different Node version, or a cache that is being restored from a run with different inputs. Reproduce the CI conditions before changing the lockfile, because regenerating it hides the real cause.

Terminal

# match the runner exactly, then install from a clean slate
node --version && npm --version
rm -rf node_modules
npm ci --foreground-scripts

# if that succeeds locally but fails in CI, the difference is the cache
# or the package-manager version, not your lockfile

Common causes

Two npm installs running concurrently

Parallel CI steps, a Makefile target, or a postinstall hook that itself runs npm install can start a second install while the first holds the tree, triggering the guard.

A leftover lock from a killed install

If a prior install was cancelled or OOM-killed, a stale _cacache/lock state in ~/.npm can make the next npm think a tree is already in progress.

How to fix it

Serialize installs and clear stale state

Ensure only one install runs, then clear the npm cache locks before retrying.

Terminal

# make sure nothing else runs npm at the same time
rm -rf node_modules
npm cache clean --force
npm ci

Remove the concurrency

Audit postinstall/prepare scripts for nested npm install calls.
In CI, do not run two install steps for the same project in parallel.
If a matrix shares a cache dir, give each leg its own npm cache (--cache).

Verify the fix survives a cold cache

A green run immediately after a fix often proves nothing, because it restored a cache written before the change. Force a cold install once to confirm the fix is real.

.github/workflows/ci.yml

# temporarily bust the cache key to prove the fix on a cold runner
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: npm
    cache-dependency-path: package-lock.json
# then bump this suffix once, run, and remove it
#   key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}-v2

How to prevent it

Run exactly one install per project, sequentially.
Avoid lifecycle scripts that re-invoke npm install.
Give parallel jobs isolated npm cache directories.

Frequently asked questions

What causes npm "Tracker idealTree already exists"?

There are 2 common causes: two npm installs running concurrently and a leftover lock from a killed install. Parallel CI steps, a Makefile target, or a postinstall hook that itself runs npm install can start a second install while the first holds the tree, triggering the guard.

How do I fix npm "Tracker idealTree already exists"?

There are 2 fixes depending on which cause you have: serialize installs and clear stale state and remove the concurrency. Work through them in order, since the first is the most common.

What does npm "Tracker idealTree already exists" actually mean?

An install fails almost immediately with "Tracker "idealTree" already exists".

How do I stop npm "Tracker idealTree already exists" happening again?

Run exactly one install per project, sequentially. The prevention section lists 3 changes that keep it from recurring.