Gagal Pasang Package? Cara Mengatasi Npm Install Error tanpa Rusak Proyek

Cara mengatasi npm install error yang aman adalah membaca pesan error lengkap dulu, bukan langsung hapus folder atau pakai flag paksa. Kebanyakan gagal pasang package di Node.js berasal dari koneksi ke registry, konflik versi dependency, izin folder, atau cache yang rusak.

Jalankan node -v dan npm -v sebelum mengubah apa pun. Pastikan versi Node sesuai kebutuhan proyek di package.json, terutama bagian engines.

Penyebab Npm Install Error Paling Sering di Node.js

npm menampilkan kode error yang berbeda untuk masalah yang berbeda. Folder node_modules jarang jadi akar masalah.

  • Network error: kode EAI_AGAIN, ETIMEDOUT, ECONNRESET, atau ENOTFOUND. Penyebabnya koneksi putus, DNS bermasalah, proxy kantor, atau registry npm sedang gangguan.
  • Permission EACCES: npm tidak boleh menulis ke folder proyek atau cache global. Sering terjadi setelah install Node dengan sudo atau di folder milik root.
  • Dependency conflict ERESOLVE: dua package meminta versi dependency yang tidak cocok. Umum muncul setelah tambah package baru atau update versi major.
  • Error build native: package butuh kompilasi lewat node-gyp atau Python. Gejalanya ada tulisan gyp ERR!, ENOENT, atau gagal build binding.

Baca log dari bawah ke atas. Baris bawah berisi ringkasan error, baris atas berisi perintah yang gagal. File log lengkap biasanya bernama npm-debug.log atau tersimpan di folder cache npm.

Tabel Diagnosis Cepat Npm Install Error

Pesan Error Penyebab Arah Solusi
ERESOLVE could not resolve Versi peer dependency bertabrakan Selaraskan versi, jangan langsung pakai force
ETIMEDOUT / EAI_AGAIN Koneksi atau registry bermasalah Cek internet, proxy, dan registry npm
EACCES permission denied Izin tulis folder ditolak Perbaiki kepemilikan folder proyek
ENOENT package-lock.json Lockfile hilang atau tidak sinkron Jalankan install ulang terkontrol
gyp ERR! build error Tool build native belum lengkap Pasang build tools sesuai OS

Flag --force dan --legacy-peer-deps bisa menyembunyikan konflik versi. Akibatnya aplikasi jalan saat install, lalu error saat runtime. Hapus package-lock.json juga berisiko menaikkan banyak versi sekaligus. Hapus node_modules aman untuk install ulang, tetapi tidak memperbaiki konflik versi.

Langkah Memperbaiki Npm Install Error dengan Aman

  1. Simpan pesan error lengkap. Catat kode seperti ERESOLVE, nama package, dan versi yang bermasalah.
  2. Verifikasi cache dan environment. Jalankan perintah diagnostik berikut:
node -v
npm -v
npm cache verify
npm ls nama-package-bermasalah
npm config get registry
  1. Periksa koneksi dan registry. Pastikan value registry mengarah ke registry resmi. Uji koneksi tanpa VPN dulu, lalu periksa konfigurasi proxy bila memakai jaringan kantor.
  2. Perbaiki versi dependency. Buka package.json, cari package dari log ERESOLVE, lalu samakan versi major yang diminta package lain. Update satu package dulu, jangan semua sekaligus.
  3. Hapus node_modules hanya bila folder install lama rusak atau tidak sinkron. Biarkan package-lock.json tetap ada agar versi dependency tidak berubah liar.
  4. Jalankan npm install ulang dan baca output sampai selesai. Bila masih gagal, perbaiki error baru yang muncul, bukan mengulang perintah yang sama.

FAQ

Apakah boleh pakai –legacy-peer-deps setiap install gagal?

Tidak. Gunakan hanya sebagai diagnosis sementara, lalu perbaiki versi dependency yang bertabrakan.

Kenapa npm install tetap gagal setelah hapus node_modules?

Karena akar masalah ada di package.json, lockfile, cache, koneksi, atau izin folder.

Kapan harus update Node.js untuk mengatasi npm install error?

Update bila log menyebut versi Node tidak didukung atau package butuh fitur Node yang lebih baru.