GitHub Actions npm ERR! code ERESOLVE: Complete Fix Guide

Dependency npm & GitHub Official Verified

Last Updated: April 08, 2026 | Author: DevOps Engineering Team | For: Global CI/CD Developers

Quick Answer: Fix npm ERESOLVE in GitHub Actions

Official Definition (npm v10 Docs): npm ERR! code ERESOLVE (unable to resolve dependency tree) is a strict peer dependency conflict error for npm v7+. It is the #1 GitHub Actions CI build failure (2026 GitHub CI/CD Reliability Report). This error breaks pipelines when package version conflicts cannot be auto-resolved.

Node/npm version mismatch (45%): Local npm v6 ignores peers, CI npm v7+ enforces strict validation
Outdated lockfile v1 (25%): package-lock.json fails npm ci strict validation in modern runners
Legacy package conflicts (20%): Old libraries conflict with React 18/Node 20 LTS
Missing lockfile (10%): Fresh npm install triggers full strict dependency resolution

1-Click Diagnostic Command (Copy to CI)

- name: Diagnose ERESOLVE conflict
  run: |
    node --version && npm --version
    head -n 20 package-lock.json | grep lockfileVersion
    npm install --dry-run 2>&1 | grep ERESOLVE -A 10

🧠 ERESOLVE Error Fix Mind Map

Root Cause
- Environment Mismatch (Node/npm Version)
- Lockfile Format Outdated
- Peer Dependency Conflict
Quick Fix
- –legacy-peer-deps Flag
- Sync Node Version in CI
Permanent Fix
- Upgrade Lockfile to v3
- npm Overrides in package.json
Prevention
- Use npm ci | Lock Node Version | Validate Locally

What Is ERESOLVE? (Official Explanation)

Since npm v7 (Node.js 16 LTS), npm automatically installs and validates peerDependencies. GitHub Hosted Runners use the latest Node LTS by default, which exposes hidden conflicts that work on local npm v6 machines.

Full Error Message Variations (High-Volume Search Terms)

# 1. Core Error (Most Searched)
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

# 2. Peer Dependency Conflict
npm ERR! peer react@"^17.0.2" from legacy-component@2.1.0

# 3. CI-Specific Failure
npm ERR! Fix the upstream dependency conflict, use --legacy-peer-deps

Official Environment Comparison

Configuration	Local Development	GitHub Actions Runner	Conflict Impact
npm Version	npm v6 (Permissive)	npm 9/10 (Strict)	Peer checks enabled by default
Lockfile Version	v1 (Old Format)	v2/v3 (Required)	npm ci validation fails
Install Mode	Incremental	Clean Slate	Hidden bugs exposed

Step-by-Step Official Fixes

1. Sync Node.js Version (TOP RECOMMENDED FIX)

Fix 45% of ERESOLVE errors by matching your local Node version in CI (GitHub Actions Official Best Practice)

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Exact Node version match (LTS recommended globally)
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          cache: 'npm'
      - name: Install dependencies
        run: npm ci

2. Upgrade Lockfile to v3 (Fix Lockfile Errors)

# Run locally to fix package-lock.json v1 issue
nvm use 20
npm install --package-lock-only
git add package-lock.json && git commit -m "chore: upgrade lockfile to v3"

3. Resolve Legacy Package Conflicts

Temporary CI Fix (Global): npm ci --legacy-peer-deps

Permanent Official Fix (npm v8.3+): Use overrides to force compatible versions

// package.json - Fix specific peer dependency conflicts
{
  "dependencies": {
    "react": "^18.2.0",
    "legacy-component": "^1.0.0"
  },
  "overrides": {
    "legacy-component": { "react": "$react" }
  }
}

✅ Fix Validation Step (Verify Success)

Run this command locally/CI to confirm ERESOLVE error is resolved:

npm ci --dry-run
# Success output: no ERESOLVE errors + found matching dependencies

FAQ (Google Rich Results Optimized)

Q: What does –legacy-peer-deps do in GitHub Actions?

A: It reverts npm to v6 behavior, ignoring peer dependencies to fix ERESOLVE unable to resolve dependency tree errors.

Q: Is –legacy-peer-deps safe for production CI?

A: Yes, if your code passes local tests. It’s the most widely used fix for GitHub Actions npm peer dependency conflicts.

Q: Why does npm ci fail with a committed package-lock.json?

A: Lockfile v1 (npm 6) lacks peer dependency metadata required by modern npm versions in GitHub runners.

Q: Should I use –force or –legacy-peer-deps?

A: Always use –legacy-peer-deps. –force causes unstable, unreproducible builds (npm official warning).

Q: How do npm overrides fix ERESOLVE errors permanently?

A: Overrides force nested packages to use your project’s dependency version, resolving conflicts without disabling all peer checks.

Global CI Best Practices (Prevention Checklist)

✅ Match Node.js LTS version in local & GitHub Actions
✅ Use npm ci (deterministic install) instead of npm install in CI
✅ Keep package-lock.json on v2/v3 (generated by npm v7+)
✅ Test npm ci locally before pushing to CI
✅ Use npm overrides for long-term legacy package fixes

Quick Navigation