Cara Mengatasi npm ERR! ERESOLVE unable to resolve dependency tree [Panduan Terbaru 2026]

Pernahkah Anda menemui error “npm ERR! ERESOLVE unable to resolve dependency tree” saat menjalankan npm install di proyek Node.js? Error ini adalah masalah umum yang dihadapi banyak developer setiap hari karena aturan resolusi dependensi yang lebih ketat yang diperkenalkan di npm 7 dan versi berikutnya. Dalam artikel ini, kami akan menjelaskan secara detail penyebab error ini, solusi spesifik, dan langkah-langkah pencegahan berdasarkan informasi terbaru tahun 2026.

Apa Itu Error Ini? Gejala Saat Terjadi
Penyebab Error Ini
Solusi 1: Gunakan Flag –legacy-peer-deps (Direkomendasikan)
Solusi 2: Lakukan Instalasi Bersih
Solusi 3: Sesuaikan Versi Paket Secara Manual (Lanjutan)
Cara Mencegah Error Ini
Ringkasan
Referensi

Apa Itu Error Ini? Gejala Saat Terjadi

“npm ERR! ERESOLVE unable to resolve dependency tree” adalah error yang terjadi ketika npm mendeteksi kombinasi versi paket yang tidak kompatibel saat membangun pohon dependensi proyek. Secara spesifik, Anda akan melihat pesan error seperti ini:

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 some-package@2.0.0
npm ERR! node_modules/some-package
npm ERR!   some-package@"^2.0.0" from the root project

Ketika error ini terjadi, perintah npm install terhenti, dan paket yang diperlukan tidak terinstal. Akibatnya, proyek tidak dapat di-build atau dijalankan. Error ini umumnya terjadi dalam situasi berikut:

Saat mengkloning proyek yang ada dan menginstal dependensi
Saat mencoba menambahkan paket baru
Setelah memperbarui versi Node.js atau npm
Selama build otomatis di pipeline CI/CD

Masalah yang ditampilkan sebagai peringatan sebelum npm 6 sekarang diperlakukan sebagai error dari npm 7 dan seterusnya, yang secara signifikan meningkatkan frekuensi menemui error ini.

Penyebab Error Ini

Penyebab 1: Konflik Peer Dependency

Penyebab paling umum adalah konflik peer dependency. Peer dependency adalah mekanisme di mana sebuah paket menyatakan “jika Anda menggunakan paket ini, Anda memerlukan versi spesifik dari paket lain.”

Misalnya, jika library UI berbasis React memerlukan React 17, tetapi proyek Anda menggunakan React 18, terjadi konflik peer dependency. Ketika beberapa paket memerlukan versi React yang berbeda, npm tidak dapat membangun pohon dependensi.

Masalah ini sering terjadi selama pembaruan versi mayor untuk framework seperti React, Angular, dan Vue. Karena butuh waktu bagi library pihak ketiga untuk mendukung versi baru, ketidakcocokan versi sering terjadi antara proyek dan paket dependen.

Penyebab 2: Resolusi Dependensi Ketat di npm 7 dan Setelahnya

Perubahan yang diperkenalkan di npm 7 secara fundamental mengubah cara peer dependency ditangani. Sebelum npm 7, konflik peer dependency hanya ditampilkan sebagai peringatan, dan instalasi dilanjutkan. Namun, dari npm 7 dan seterusnya, konflik peer dependency diperlakukan sebagai error, dan instalasi terhenti.

Perubahan ini diperkenalkan untuk mendeteksi masalah dependensi lebih awal, tetapi telah menyebabkan masalah kompatibilitas dengan banyak proyek yang ada dan paket lama. Error ini sering terjadi, terutama di proyek yang menggunakan paket yang tidak dipelihara untuk waktu yang lama.

Penyebab 3: Ketidakkonsistenan Antara package-lock.json dan package.json

Ketika file package-lock.json tidak sinkron dengan package.json, ini juga dapat menyebabkan error. Ini terjadi dalam situasi seperti:

Menggunakan file lock yang dihasilkan oleh versi npm yang berbeda
Tidak memperbarui file lock setelah mengedit package.json secara manual
Beberapa developer bekerja di lingkungan yang berbeda
Kerusakan file lock selama penggabungan git

Penyebab 4: Masalah Cache

Jika data lama atau rusak tersisa di cache npm, resolusi dependensi mungkin gagal. Ini sangat mungkin terjadi ketika sering mengganti versi paket atau ketika unduhan terganggu karena masalah jaringan.

Penyebab 5: Masalah Kompatibilitas Versi Node.js

Error ini juga dapat terjadi ketika versi Node.js yang Anda gunakan tidak cocok dengan versi yang diperlukan oleh paket yang Anda coba instal. Beberapa paket hanya berfungsi dengan versi Node.js tertentu, membuat manajemen versi Node.js menjadi penting.

Solusi 1: Gunakan Flag –legacy-peer-deps (Direkomendasikan)

Solusi termudah dan teraman adalah menggunakan flag --legacy-peer-deps. Dengan menambahkan flag ini, Anda dapat menggunakan algoritma resolusi dependensi era npm 6, mengabaikan konflik peer dependency dan melanjutkan instalasi.

Langkah 1: Penggunaan Dasar

Jalankan perintah berikut di terminal Anda:

npm install --legacy-peer-deps

Saat menginstal paket tertentu:

npm install nama-paket --legacy-peer-deps

Misalnya, saat menginstal library terkait React:

npm install react-router-dom --legacy-peer-deps

Langkah 2: Menjadikannya Pengaturan Default via File .npmrc

Jika menambahkan flag setiap saat terasa merepotkan, Anda dapat membuat file .npmrc di direktori root proyek untuk mengaktifkan --legacy-peer-deps secara default:

# Jalankan di root proyek
echo "legacy-peer-deps=true" > .npmrc

Atau, untuk menerapkannya sebagai pengaturan global:

npm config set legacy-peer-deps true

Ini akan secara otomatis menerapkan --legacy-peer-deps ke perintah npm install di masa mendatang.

Langkah 3: Memanfaatkan resolutions package.json (Opsional)

Saat menggunakan Yarn atau ketika kontrol yang lebih detail diperlukan, Anda dapat menambahkan field resolutions ke package.json untuk memaksa versi paket tertentu:

{
  "resolutions": {
    "react": "18.2.0"
  }
}

Catatan Penting

--legacy-peer-deps adalah opsi yang aman, tetapi ini berarti mengabaikan peringatan peer dependency. Ini menyiratkan bahwa masalah kompatibilitas antar paket mungkin terlewatkan. Pastikan untuk menguji bahwa aplikasi Anda berfungsi dengan benar sebelum men-deploy ke produksi.

Selain itu, flag ini hanya melonggarkan pemeriksaan peer dependency sambil mempertahankan pemeriksaan keamanan lainnya. Oleh karena itu, ini adalah pilihan yang lebih aman daripada flag --force.

Solusi 2: Lakukan Instalasi Bersih

Ketika pohon dependensi kompleks dan kusut, instalasi bersih efektif. Ini memungkinkan Anda membersihkan dependensi bermasalah yang ada dan membangun ulang dari kondisi bersih.

Langkah 1: Hapus Dependensi yang Ada

Pertama, hapus direktori node_modules dan package-lock.json:

Untuk Windows:

rmdir /s /q node_modules
del package-lock.json

Untuk macOS/Linux:

rm -rf node_modules
rm package-lock.json

Langkah 2: Bersihkan Cache npm

Bersihkan cache karena cache lama mungkin menyebabkan masalah:

npm cache clean --force

Langkah 3: Instal Ulang Dependensi

Instal ulang dependensi dari kondisi bersih:

npm install

Jika error masih terjadi, kombinasikan dengan --legacy-peer-deps:

npm install --legacy-peer-deps

Perintah Satu Baris

Untuk menjalankan langkah-langkah di atas bersamaan:

Untuk macOS/Linux:

rm -rf node_modules package-lock.json && npm cache clean --force && npm install --legacy-peer-deps

Untuk Windows (PowerShell):

Remove-Item -Recurse -Force node_modules; Remove-Item package-lock.json; npm cache clean --force; npm install --legacy-peer-deps

Metode ini sangat efektif ketika mengambil alih proyek dari developer lain atau melanjutkan proyek yang telah ditinggalkan untuk waktu yang lama.

Solusi 3: Sesuaikan Versi Paket Secara Manual (Lanjutan)

Jika Anda menginginkan solusi fundamental, Anda dapat menyesuaikan versi paket secara manual. Ini memungkinkan Anda membangun dependensi yang stabil jangka panjang.

Langkah 1: Analisis Pesan Error Secara Detail

Pesan error menunjukkan paket mana yang memerlukan versi apa:

npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from some-library@2.0.0

Dalam contoh ini, some-library@2.0.0 memerlukan React 17.

Langkah 2: Identifikasi Versi yang Kompatibel

Cari paket di situs web npmjs dan periksa versi yang kompatibel. Seringkali, versi terbaru dari sebuah paket mendukung versi React yang lebih baru:

npm view some-library versions
npm view some-library peerDependencies

Langkah 3: Perbarui package.json

Setelah Anda menemukan versi yang kompatibel, perbarui package.json:

{
  "dependencies": {
    "some-library": "^3.0.0"
  }
}

Atau, saat melakukan downgrade untuk mencocokkan versi React tertentu:

{
  "dependencies": {
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  }
}

Langkah 4: Gunakan npm-check-updates (Opsional)

Saat memperbarui beberapa paket sekaligus, tool npm-check-updates sangat berguna:

npx npm-check-updates -u
npm install

Menggunakan Field overrides (npm 8.3+)

Dari npm 8.3 dan seterusnya, Anda dapat menambahkan field overrides ke package.json untuk menimpa versi dependensi tertentu:

{
  "overrides": {
    "some-library": {
      "react": "^18.0.0"
    }
  }
}

Ini memungkinkan Anda menimpa paksa versi React yang diperlukan oleh some-library ke 18. Namun, metode ini dapat menyebabkan perilaku yang tidak terduga, jadi uji secara menyeluruh.

Cara Mencegah Error Ini

Pembaruan Dependensi Secara Berkala

Dengan memperbarui dependensi proyek Anda secara berkala, Anda dapat meminimalkan konflik peer dependency. Periksa paket yang usang setiap minggu dengan perintah npm outdated:

npm outdated

Manajemen Versi Node.js dan npm

Gunakan alat manajemen versi seperti nvm untuk menggunakan versi Node.js yang sesuai untuk setiap proyek:

# Buat file .nvmrc
echo "18.17.0" > .nvmrc

# Jalankan di direktori proyek
nvm use

Langkah-langkah untuk Pipeline CI

Untuk menghindari error ini di pipeline CI/CD, sertakan file .npmrc di repositori Anda atau tambahkan flag ke perintah instal:

# Contoh GitHub Actions
- name: Install dependencies
  run: npm ci --legacy-peer-deps

Menyatukan Aturan dalam Tim

Saat mengembangkan sebagai tim, penting untuk menyatukan aturan berikut:

Versi Node.js dan npm yang digunakan
Aturan untuk meng-commit package-lock.json
Proses verifikasi saat menambahkan paket baru

Ringkasan

Error “npm ERR! ERESOLVE unable to resolve dependency tree” adalah masalah umum yang disebabkan oleh pemeriksaan dependensi yang lebih ketat dari npm 7 dan seterusnya. Untuk mengatasi error ini, artikel ini memperkenalkan tiga pendekatan:

Flag –legacy-peer-deps: Metode termudah dan teraman. Ini menyelesaikan sebagian besar kasus
Instalasi bersih: Efektif ketika dependensi kompleks dan kusut
Penyesuaian versi paket: Metode lanjutan untuk mencapai solusi fundamental

Pertama, coba npm install --legacy-peer-deps, dan jika itu tidak berhasil, coba instalasi bersih. Dalam jangka panjang, penting untuk memperbarui dependensi secara berkala dan menjaga kesehatan proyek.

Jika error ini tidak dapat diselesaikan atau jika masalah terjadi dengan paket tertentu, periksa issues di repositori GitHub paket tersebut atau cari masalah serupa di Stack Overflow.