npm CLI npm dependencies version-conflict
Nina Johansson Site Reliability Engineer

npm ERR! ERESOLVE unable to resolve dependency tree

Encountering npm ERR! ERESOLVE means npm cannot find a compatible set of package versions for your project; this guide explains how to fix it.

What This Error Means

The npm ERR! ERESOLVE unable to resolve dependency tree error indicates that npm has failed to find a single, consistent set of package versions that satisfies all the declared dependencies in your package.json file. Imagine a complex puzzle where multiple pieces (your project, its direct dependencies, and their own dependencies) all require specific versions of other pieces. This error means npm couldn't find a way to fit all those requirements together without conflicts.

Essentially, npm tries to build a "dependency tree" where each package in the tree has a version that meets the requirements of all its parents and children. When two different packages in your project (or their respective transitive dependencies) demand incompatible versions of a third package, npm throws ERESOLVE because it cannot resolve the conflict automatically. It's a signal that manual intervention or a different approach is needed to untangle the web of requirements.

Why It Happens

This error primarily occurs because of conflicting version requirements among your project's dependencies. Modern JavaScript projects often have a deep dependency graph, meaning your direct dependencies rely on other packages, which in turn rely on even more packages. These are called "transitive dependencies."

When you specify a dependency in your package.json like "react": "^18.0.0", you're telling npm to install any version of React that is 18.x.x but not 19.0.0 or higher. This flexibility is managed by semantic versioning (SemVer). The problem arises when:

  1. Direct Conflict: Your project directly depends on package-A@^1.0.0 and package-B@^2.0.0, but package-A specifically requires lodash@^3.0.0 and package-B requires lodash@^4.0.0. npm can't install both lodash v3 and v4 simultaneously at the top level, so it fails.
  2. Transitive Conflict: Your project depends on package-X@^1.0.0. package-X depends on utility-lib@^1.0.0. You also depend on package-Y@^2.0.0, which depends on utility-lib@^2.0.0. Again, a conflict for utility-lib.
  3. Peer Dependency Issues: Some packages, especially plugins or UI component libraries, declare "peer dependencies." This means they expect your project to have a certain version of another package (like React or Webpack) installed, rather than installing it themselves. If your project's version of that peer dependency doesn't match the package's expectation, ERESOLVE can occur. npm often tries to resolve these by defaulting to npm install --legacy-peer-deps behavior in newer versions, but if even that fails, you'll see the error.

Common Causes

In my experience running various Node.js services, ERESOLVE typically stems from a few recurring scenarios:

  • Adding a New Dependency: Introducing a new package into an existing project can often trigger this, especially if the new package has strict or conflicting requirements with an already established dependency. I've seen this repeatedly when integrating new third-party libraries.
  • Upgrading Existing Dependencies: Bumping a major version of a direct dependency (e.g., from library@1.x to library@2.x) can introduce breaking changes in its own dependency tree, leading to conflicts with other parts of your project.
  • Outdated package-lock.json: If your package-lock.json file is old or out of sync with your package.json (e.g., after manual edits to package.json without running npm install), npm might struggle to reconcile the locked versions with new requirements. This is a common culprit in CI/CD pipelines where caches might be involved.
  • npm or Node.js Version Mismatch: Different versions of npm (especially npm v7+ compared to npm v6) handle dependency resolution differently. npm v7+ is much stricter about peer dependencies, which can lead to ERESOLVE errors where previous versions might have issued a warning or installed anyway. Similarly, certain packages might only support specific Node.js versions.
  • Sub-dependency Breaking Changes: Less common but equally frustrating: a sub-dependency (a dependency of your dependency) might have released a breaking change or tightened its own dependency requirements, and your main dependency hasn't updated to accommodate it, leading to a transitive conflict.

Step-by-Step Fix

When facing npm ERR! ERESOLVE, a systematic approach is best. Don't just blindly try flags; read the output and understand the conflict.

  1. Examine the Error Message Carefully: npm usually provides detailed output about which packages are conflicting and what versions they require. Look for lines like Conflicts with dependency "some-package@X.Y.Z". This is your primary clue. Note down the conflicting packages and their version requirements.

    npm ERR! code ERESOLVE npm ERR! ERESOLVE unable to resolve dependency tree npm ERR! npm ERR! While resolving: your-project@1.0.0 npm ERR! Found: react@18.2.0 npm ERR! node_modules/react npm ERR! react@"^18.2.0" from the root project npm ERR! npm ERR! Could not resolve dependency: npm ERR! peer react@"^17.0.0" from react-dom-testing-library@11.2.1 npm ERR! node_modules/react-dom-testing-library npm ERR! react-dom-testing-library@"^11.2.1" from the root project npm ERR! npm ERR! Fix the upstream dependency conflict, or retry npm ERR! with --force or --legacy-peer-deps npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
    In this example, the conflict is between react@18.2.0 (required by your project) and react-dom-testing-library@11.2.1 which peers react@^17.0.0.

  2. Try npm install --legacy-peer-deps (for peer dependency issues): If the error message explicitly points to "peer dependencies," this flag often resolves the issue. It tells npm to ignore peer dependency conflicts and proceed with the installation using the versions already installed or resolvable.

    • Caveat: While convenient, this might lead to runtime issues if the packages truly need specific peer versions. Use this as a temporary fix or if you're confident the versions are compatible in practice.

    bash npm install --legacy-peer-deps

  3. Try npm install --force (as a last resort): This flag is a sledgehammer. It bypasses the dependency tree resolver entirely and forces npm to install packages even if they conflict.

    • Serious Caveat: Only use this if you understand the specific conflict and are willing to accept potential breakage. I've only used --force in very specific, controlled development environments for quick testing, never in production builds. This can lead to a broken node_modules or runtime errors that are hard to debug later.

    bash npm install --force

  4. Update Direct Dependencies: Often, the packages you directly depend on have released new versions that resolve internal dependency conflicts.

    • First, run npm update to update packages within their specified SemVer ranges.
    • If that doesn't work, consider manually updating specific conflicting packages in your package.json to their latest compatible versions. Tools like npm-check-updates (or ncu) can help identify available major version updates.

    ```bash
    npm update

    To find potential major version updates:

    npx npm-check-updates -u
    `` After updatingpackage.jsonusingncu -u, runnpm install`.

  5. Clean Cache and Reinstall: A corrupted or stale npm cache or package-lock.json can sometimes cause strange resolution issues.

    • Delete node_modules and package-lock.json.
    • Clear the npm cache.
    • Run npm install again. This ensures a fresh installation from scratch.

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

  6. Analyze and Downgrade/Upgrade Conflicting Packages: If the error persists, you'll need to manually inspect the conflicting package mentioned in the ERESOLVE output.

    • Use npm list <conflicting-package-name> to see which of your direct dependencies are pulling in different versions of the problematic package.
    • Based on this, you might need to:
      • Downgrade: If a newer version of one of your direct dependencies is causing a conflict, try temporarily downgrading it to an earlier version that doesn't exhibit the conflict.
      • Upgrade: If an older dependency is pulling in a very old, conflicting sub-dependency, check if there's a newer major version of that dependency available that has updated its own sub-dependencies.
        This often involves trial and error, modifying your package.json, and running npm install until the tree resolves.

  7. Check Node.js and npm Versions: Ensure your Node.js and npm versions are compatible with your project's dependencies. Some packages specify a minimum (or maximum) supported Node.js version. If you're on an older npm version, upgrading to npm v7 or higher might help resolve conflicts more intelligently (or stricter, leading to ERESOLVE where you previously had warnings). Use a tool like nvm (Node Version Manager) to manage Node.js versions easily.

Code Examples

Here are some concise, copy-paste ready commands for the common fixes:

Installing with flags to bypass strict resolution:

# For peer dependency conflicts (npm v7+ strictness)
npm install --legacy-peer-deps

# Force installation, bypassing all conflicts (use with extreme caution)
npm install --force

Updating dependencies:

# Update packages within their current major/minor ranges
npm update

# Interactively check for major version updates (requires 'npm-check-updates')
npx npm-check-updates
# To apply updates found by ncu:
npx npm-check-updates -u && npm install

Cleaning and reinstalling:

# Remove node_modules and package-lock.json, clear cache, and reinstall
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Inspecting dependency trees:

# List all installed packages
npm list

# List a specific package and its dependants
npm list <package-name>

# Check deep dependency issues for a package
npm ls <package-name>

Environment-Specific Notes

The ERESOLVE error can manifest differently or require distinct troubleshooting steps depending on your environment.

Cloud / CI/CD Pipelines

  • Caching: In CI/CD, stale npm caches or node_modules directories are a prime suspect. If a previous build cached node_modules or package-lock.json that are no longer compatible with changes in package.json, you'll hit this error.
    • Solution: Ensure your CI pipeline has a step to explicitly clear the cache (npm cache clean --force) or to remove node_modules and package-lock.json before npm install. Many CI platforms offer ways to invalidate or rebuild dependency caches. I've found that ensuring a clean slate is often the most reliable way to prevent ERESOLVE in CI.
  • Node.js/npm Version: CI environments should ideally pin the exact Node.js and npm versions. If your local Node.js version is 18.x and your CI uses 16.x (or even 18.x but with an older npm version), you can get different resolution behaviors.

Docker Containers

  • Image Layers: If you're building Docker images, node_modules might be built on an earlier layer. If package.json changes later without invalidating that layer, you could get a mismatch.
    • Solution: Follow best practices for Dockerizing Node.js apps: copy package.json and package-lock.json first, then run npm install, and then copy the rest of your application code. This ensures npm install runs with the correct package.json. Use multi-stage builds to keep the final image lean and focused.

    • Example Dockerfile snippet:
      ```dockerfile
      FROM node:18-alpine AS builder
      WORKDIR /app
      COPY package*.json ./
      RUN npm install --ignore-scripts # Add --force or --legacy-peer-deps if needed here
      COPY . .
      RUN npm run build

      FROM node:18-alpine AS runner
      WORKDIR /app
      COPY --from=builder /app/node_modules ./node_modules
      COPY --from=builder /app/dist ./dist # Or wherever your built app is
      CMD ["node", "dist/main.js"]
      ```

Local Development

  • IDE Integration: Some IDEs (like VS Code) have built-in npm integration. Ensure your IDE isn't doing anything unexpected in the background.
  • Global npm packages: While less common for ERESOLVE, sometimes globally installed packages can interfere if they shadow or conflict with local project dependencies. In my experience, isolating project dependencies is always safer.
  • ~/.npm/_cache: Your user-level npm cache can occasionally become corrupted. Running npm cache clean --force will clear this out.

Frequently Asked Questions

Q: Is npm install --force ever truly safe to use?
A: Rarely for production builds, but potentially in very specific local development scenarios. It tells npm to ignore conflicts, which will lead to an invalid dependency tree. This can cause runtime errors or unexpected behavior that is very difficult to debug later. Use it only if you fully understand the specific conflict it's bypassing and accept the risks. From a reliability perspective, I would never allow --force in a CI/CD pipeline or for any production artifact.

Q: What are "peer dependencies" and why do they cause ERESOLVE?
A: Peer dependencies are dependencies that a package (often a plugin or library) expects its consuming project to provide, rather than installing them itself. For example, a React UI library might declare react and react-dom as peer dependencies. npm v7+ is very strict about ensuring that the project's installed peer dependency version satisfies the range declared by the dependent package. If it doesn't, ERESOLVE occurs. The --legacy-peer-deps flag tells npm to install even if the peer dependency ranges aren't perfectly met.

Q: How does package-lock.json factor into ERESOLVE?
A: package-lock.json locks down the exact version of every package in your node_modules tree, including transitive dependencies. If you manually edit package.json or try to update a dependency, but the package-lock.json still insists on an older, conflicting version of a transitive dependency, npm might get confused and throw ERESOLVE. Deleting package-lock.json and node_modules and then running npm install forces npm to resolve the entire tree from scratch based solely on package.json and rebuild the lock file.

Q: Should I always upgrade Node.js/npm when I see this error?
A: Not necessarily. While newer npm versions sometimes have better dependency resolution algorithms, blindly upgrading might introduce new conflicts or break compatibility with other packages. Always check your project's documented Node.js compatibility. If you're on a very old Node.js/npm version (e.g., Node.js 12 with npm 6), upgrading to a more recent LTS version (e.g., Node.js 18 with npm 8/9) can be beneficial, but do so methodically and test thoroughly.