Solusi: npm error class extends value undefined is not a constructor or null

Error ini termasuk yang paling membingungkan di ekosistem Node.js karena pesannya terasa abstrak—tidak langsung menunjuk file atau paket mana yang bermasalah. Padahal, di balik pesan ini ada pola penyebab yang sangat bisa diprediksi. Artikel ini membongkar satu per satu: apa maksud error ini, kenapa muncul, cara memastikan penyebabnya, dan langkah fix yang permanen—bukan sekadar workaround yang besok-besok muncul lagi.

Arti Pesan Error Tersebut

Berikut adalah kutipan pesan error asli yang muncul di terminal:

npm ERR! code 1
npm ERR! path /home/user/project/node_modules/pacote
npm ERR! command failed
npm ERR! command sh -c node --openssl-legacy-provider gyp.js
npm ERR! /path/node_modules/npm/node_modules/@npmcli/git/lib/index.js:1
npm ERR! class Git extends _git {}
npm ERR!            ^
npm ERR! TypeError: Class extends value undefined is not a constructor or null

Variasi lain yang sama seringnya muncul:

npm install
# ...
TypeError: Class extends value undefined is not a constructor or null
    at Object.<anonymous> (/usr/lib/node_modules/npm/node_modules/@npmcli/git/lib/index.js:1:20)

Arti singkat: Ada sebuah class di dalam internal npm yang mencoba mewarisi (extends) class lain, tetapi class induk yang seharusnya di-extend mengembalikan undefined. Dalam JavaScript, class A extends B mensyaratkan B berupa constructor function atau null. Kalau B adalah undefined, runtime langsung melempar TypeError.

Kenapa error ini muncul? Secara praktis, ini hampir selalu disebabkan oleh inkonsistensi versi antara npm yang terinstall di sistem dengan versi Node.js yang sedang aktif, atau oleh korupsi pada instalasi npm itu sendiri—entah karena upgrade parsial, karena nvm switch yang tidak bersih, atau karena node_modules dan package-lock.json berada dalam state yang saling kontradiksi. npm versi 7 ke atas mengadopsi arsitektur internal berbasis class inheritance yang ketat; ketika satu modul internal gagal di-resolve, efeknya cascade ke class lain yang mencoba mewarisinya, dan di situlah error ini muncul.

Kenapa Ini Terjadi

Berikut adalah root cause yang paling sering, diurutkan dari frekuensi tertinggi berdasarkan laporan di GitHub issue tracker npm dan StackOverflow:

Versi npm tidak kompatibel dengan versi Node.js yang aktif. Ini adalah penyebab nomor satu. Misalnya, Anda menginstall npm 9 secara global tetapi menjalankan Node.js 14, atau sebaliknya. Setiap major version npm dirancang untuk range Node.js tertentu; di luar range itu, modul internal bisa gagal load dan mengembalikan undefined.
Upgrade npm yang parsial atau korup. Menjalankan npm install -g npm@latest terkadang tidak mengganti semua file internal npm lama,*terutama kalau prosesnya ter-interrupt atau kalau permission file tidak konsisten. Hasilnya, ada file dari versi baru dan versi lama yang bercampur.
node_modules dan package-lock.json korup atau out-of-sync. Lock file merekam resol) resolusi dependency pada saat npm install dijalankan, tetapi kalau Anda mengubah versi Node.js di tengah-tengah development tanpa menghapus node_modules, biner-biner native addon di dalamnya bisa merujuk ke ABI versi lama yang tidak cocok.
Konflik antara npm global bawaan OS dan npm yang di-install via nvm/fnm. Di macOS dan beberapa distro Linux, Homebrew atau package manager sistem menginstal npm ke /usr/local/lib/node_modules/npm, sementara nvm menginstal ke ~/.nvm/versions/node/vXX.XX.X/lib/node_modules/npm. Kalau $PATH tidak resolve dengan benar, node dan npm bisa berasal dari dua instalasi berbeda.
Cache npm yang korup. Meskipun lebih jarang, cache yang rusak bisa menyebabkan npm menarik tarball yang incomplete, sehingga modul internal tidak ter-ekstrak dengan sempurna.

Cara memastikan penyebab mana yang Anda alami: Jalankan tiga perintah diagnostik berikut secara berurutan:

node --version
# Output yang diharapkan: v18.17.0 (contoh)

npm --version
# Output yang diharapkan: 9.6.7 (contoh)

which node && which npm
# Output yang diharapkan: keduanya dari direktori yang sama,
# misalnya:
# /home/user/.nvm/versions/node/v18.17.0/bin/node
# /home/user/.nvm/versions/node/v18.17.0/bin/npm

Kalau which node dan which npm menunjuk path yang berbeda (misalnya satu dari nvm, satu dari /usr/local/bin), penyebab nomor 4 adalah peluang terbesar. Kalau versi Node.js di bawah minimum yang didukung npm Anda (cek di npm changelog), penyebab nomor 1 sedang terjadi. Kalau keduanya konsisten tetapi error tetap muncul, lanjutkan ke pemeriksaan node_modules dan cache—penyebab nomor 2 dan 3.

Cara Memperbaiki

Langkah 1: Sinkronkan versi Node.js dan npm

Pendekatan paling langsung adalah memastikan Anda menggunakan bundel Node.js + npm yang resmi dan cocok. Cara termudah: biarkan Node.js membawa npm bawaannya, jangan upgrade npm secara terpisah.

# Jika menggunakan nvm, install versi Node LTS terbaru
nvm install --lts
# Output: Installing latest LTS version...
# Now using node v18.17.0 (npm v9.6.7)

# Set sebagai default
nvm alias default 'lts/*'
# Output: default -> lts/* (-> v18.17.0)

Verifikasi:

node --version && npm --version
# v18.17.0
# 9.6.7

Jika error hilang setelah switch versi, penyebabnya adalah inkonsistensi versi (root cause #1). Ini adalah fix permanen selama Anda tidak lagi meng-upgrade npm secara independen.

Langkah 2: Bersihkan instalasi npm yang korup

Kalau Langkah 1 tidak menyelesaikan masalah, kemungkinan instalasi npm Anda korup. Reinstall npm dari awal:

# Dengan nvm — cara terbersih
nvm uninstall 18
nvm install 18
# Output: Downloading node.js version 18...
# Installing npm v9.6.7...

# Tanpa nvm (Linux/macOS) — reinstall Node dari package manager resmi
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
# Output: nodejs_18.17.0-1nodesource1_amd64.deb

Verifikasi:

npm doctor
# Output (yang diharapkan):
# npm ok        checked 1 packages
# npm ok        All installed packages are OK

Langkah 3: Hapus node_modules dan package-lock.json, lalu install ulang

Ini menyelesaikan root cause #3. Jangan hanya hapus node_modules—package-lock.json juga harus di-regenerate karena bisa menyimpan referensi ke resolusi yang sudah tidak valid.

rm -rf node_modules package-lock.json

npm install
# Output: added 342 packages in 12s

Verifikasi:

npm ls --depth=0
# Output: daftar semua top-level dependency tanpa error

Langkah 4: Bersihkan cache npm

npm cache clean --force
# Output: npm warn using --force I sure hope you know what you are doing
# npm verb cache: cleaned in 320ms

# Verifikasi cache bersih
npm cache verify
# Output: Cache verified and compressed (~0B)

Setelah cache bersih, ulangi npm install.

Langkah 5: Perbaiki PATH conflict (root cause #4)

# Cek apakah ada konflik
which node
# /usr/local/bin/node        ← dari Homebrew/system

which npm
# /home/user/.nvm/versions/node/v18.17.0/bin/npm  ← dari nvm

Kalau keduanya berbeda, perbaiki dengan memastikan nvm (atau version manager Anda) di-load terakhir di .bashrc / .zshrc sehingga menimpa path sistem:

# Di ~/.bashrc atau ~/.zshrc, pastikan baris ini ada di PALING BAWAH:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Buka terminal baru, lalu verifikasi:

which node && which npm
# Keduanya harus dari direktori nvm yang sama

Solusi Jangka Panjang

Solusi step-by-step di atas menyelesaikan masalah saat ini, tetapi agar error ini tidak pernah muncul lagi, Anda perlu menerapkan konfigurasi dan disiplin berikut:

1. Pin versi Node.js di proyek dengan `.nvmrc`

File .nvmrc memberi sinyal ke seluruh tim versi Node.js mana yang harus dipakai. Ini mencegah seseorang menjalankan npm install dengan versi Node yang salah.

# Buat .nvmrc
echo "18" > .nvmrc

# Setiap masuk direktori proyek, jalankan:
nvm use
# Output: Found '/path/project/.nvmrc' with version <18>
# Now using node v18.17.0 (npm v9.6.7)

Agar nvm use otomatis dijalankan setiap cd ke direktori proyek, tambahkan skrip hook di shell Anda:

# Di ~/.bashrc atau ~/.zshrc
cdnvm() {
  cd "$@" && [ -f .nvmrc ] && nvm use
}

2. Tambahkan `engines` di `package.json`

Ini adalah enforcement di level npm—bukan hanya dokumentasi. Dengan "engines", npm akan refuse menjalankan install kalau versi Node tidak memenuhi syarat.

{
  "name": "my-project",
  "engines": {
    "node": ">=18.0.0 <19.0.0",
    "npm": ">=9.0.0 <10.0.0"
  },
  "engineStrict": true
}

Untuk membuat enforcement ini benar-benar memblokir (bukan cuma warning), tambahkan .npmrc:

echo "engine-strict=true" > .npmrc

Sekarang, kalau seseorang mencoba npm install dengan Node 14:

npm install
# npm ERR! code EBADENGINE
# npm ERR! engine Unsupported engine
# npm ERR! engine Not compatible with your version of Node.js

3. Jangan pernah upgrade npm secara independen

Ini adalah best practice yang sering dilanggar. Banyak tutorial menyarankan npm install -g npm@latest, tetapi ini adalah sumber utama korupsi. npm yang dibundle dengan Node.js sudah di-test untuk kompatibilitas. Kalau Anda butuh fitur npm terbaru,

Solusi: npm error class extends value undefined is not a constructor or null

Arti Pesan Error Tersebut

Kenapa Ini Terjadi

Cara Memperbaiki

Langkah 1: Sinkronkan versi Node.js dan npm

Langkah 2: Bersihkan instalasi npm yang korup

Langkah 3: Hapus node_modules dan package-lock.json, lalu install ulang

Langkah 4: Bersihkan cache npm

Langkah 5: Perbaiki PATH conflict (root cause #4)

Solusi Jangka Panjang

1. Pin versi Node.js di proyek dengan `.nvmrc`

2. Tambahkan `engines` di `package.json`

3. Jangan pernah upgrade npm secara independen

Baca juga

Mengatasi Error npm err cannot read properties of null (reading 'package')

Memperbaiki econnrefused api

Mengatasi Error modulenotfounderror tkinter

Arti Pesan Error Tersebut

Kenapa Ini Terjadi

Cara Memperbaiki

Langkah 1: Sinkronkan versi Node.js dan npm

Langkah 2: Bersihkan instalasi npm yang korup

Langkah 3: Hapus node_modules dan package-lock.json, lalu install ulang

Langkah 4: Bersihkan cache npm

Langkah 5: Perbaiki PATH conflict (root cause #4)

Solusi Jangka Panjang

1. Pin versi Node.js di proyek dengan .nvmrc

2. Tambahkan engines di package.json

3. Jangan pernah upgrade npm secara independen

Baca juga

Mengatasi Error npm err cannot read properties of null (reading 'package')

Memperbaiki econnrefused api

Mengatasi Error modulenotfounderror tkinter

1. Pin versi Node.js di proyek dengan `.nvmrc`

2. Tambahkan `engines` di `package.json`