Error npm err cannot read properties of null (reading 'package') adalah salah satu error yang cukup membingungkan di ekosistem Node.js karena pesannya tidak langsung menunjukkan file atau konfigurasi mana yang bermasalah. Error ini termasuk kategori null reference error—npm mencoba mengakses properti package dari sebuah objek yang bernilai null, dan tentu saja gagal. Dalam praktik nyata, error ini hampir selalu berkaitan dengan korupsi pada cache npm, kerusakan struktur node_modules, atau file package-lock.json yang tidak sinkron dengan package.json. Artikel ini akan membongkar pesan error ini sampai ke akarnya, memberikan langkah perbaikan yang terurut dan terverifikasi, serta membangun fondasi agar error serupa tidak muncul kembali di masa depan.
Membaca pesan error ini
Ketika error ini muncul, output di terminal biasanya terlihat seperti ini:
npm ERR! Cannot read properties of null (reading 'package')
npm ERR! A complete log of this run can be found in:
npm ERR! /home/username/.npm/_logs/2024-11-15T08_32_14_567Z-debug-0.log
Atau dalam beberapa kasus, error ini muncul bersamaan dengan stack trace yang lebih panjang:
npm ERR! Cannot read properties of null (reading 'package')
npm ERR! code 1
npm ERR! path /home/username/project/node_modules/some-package
npm ERR! errno 1
npm ERR! A complete log of this run can be found in:
npm ERR! /home/username/.npm/_logs/2024-11-15T08_32_14_567Z-debug-0.log
Dalam bahasa Indonesia sederhana, pesan ini berarti: npm mencoba membaca properti package dari sebuah objek, tetapi objek tersebut bernilai null (kosong/tidak ada), sehingga operasi gagal. Ini bukan error di kode aplikasi Anda, melainkan error internal di dalam mekanisme npm saat memproses resolusi dependensi.
Kenapa error ini muncul? Secara teknis, npm membangun sebuah pohon dependensi (dependency tree) di memori setiap kali Anda menjalankan perintah seperti npm install, npm update, atau npm ci. Setiap node di pohon itu merepresentasikan sebuah paket dan seharusnya memiliki referensi ke objek package (yang berisi metadata dari package.json paket tersebut). Ketika sebuah node bernilai null, berarti npm gagal menemukan atau mengkonstruksi metadata paket itu. Kondisi ini dipicu oleh beberapa hal: cache npm yang menyimpan data rusak, folder node_modules yang berada di kondisi partial akibat instalasi yang terputus di tengah jalan, atau package-lock.json yang merujuk ke versi paket yang sudah dihapus dari registry npm.
Penting untuk memahami bahwa error ini bukan berarti package.json proyek Anda hilang atau kosong. Masalahnya berada lebih dalam—di level internal resolver npm. Itulah sebabnya sekadar mengecek package.json tidak akan langsung menyelesaikan masalah. Anda perlu membersihkan state yang diandalkan npm untuk membuat pohon dependensi, yaitu cache, node_modules, dan package-lock.json.
Penyebab umum
Berikut adalah lima root cause yang paling sering memicu error ini, diurutkan dari yang paling banyak ditemui di lapangan:
1. Cache npm yang korup. Ini adalah penyebab paling dominan. npm menyimpan salinan paket yang sudah diunduh di cache lokal (~/.npm) untuk mempercepat instalasi berikutnya. Ketika file di cache rusak—misalnya karena proses unduh terputus, disk penuh, atau crash tak terduga—npm bisa membaca metadata yang tidak lengkap. Objek paket yang seharusnya berisi properti package menjadi null karena metadata tidak terbentuk sempurna. Anda bisa memastikan ini dengan menjalankan npm cache verify dan memperhatikan apakah ada laporan corrupted entries.
2. Folder node_modules dalam kondisi parsial atau rusak. Jika proses npm install sebelumnya diinterupsi (Ctrl+C, mati listrik, OOM kill), folder node_modules bisa berisi paket yang hanya terunduh sebagian. npm melihat direktori paket itu ada, tetapi isinya tidak lengkap—sehingga metadata yang dibaca menjadi null. Cirinya: ada folder di dalam node_modules yang kosong atau hanya berisi file package.json parsial tanpa field version atau name.
3. package-lock.json tidak sinkron dengan package.json. Ketika Anda mengubah package.json secara manual (misalnya menambah dependensi baru) tetapi lupa menjalankan npm install untuk meregenerasi package-lock.json, lockfile bisa merujuk ke resolusi yang tidak lagi valid. npm versi 7+ sangat bergantung pada lockfile; ketika lockfile merujuk ke paket yang tidak ditemukan di registry, resolver mengembalikan null. Cara memastikan: jalankan npm ls dan lihat apakah ada warning invalid atau missing.
4. Konflik versi npm global versus versi yang dipakai di proyek. Lockfile yang di-generate oleh npm v8 punya format yang berbeda dari npm v6. Jika satu anggota tim menggunakan npm v6 dan yang lain npm v8, lockfile bisa berisi struktur yang tidak dikenali oleh versi npm yang lebih lama, menyebabkan resolver gagal mem-parsing entry dan mengembalikan null. Anda bisa memastikan dengan npm --version dan membandingkannya dengan field lockfileVersion di package-lock.json (nilai 1 = npm v6, 2 = npm v7, 3 = npm v8+).
5. Paket yang dirujuk sudah di-unpublish dari registry. Jarang, tetapi bisa terjadi. Jika package-lock.json merujuk ke versi spesifik sebuah paket yang kemudian di-unpublish oleh maintainer-nya (misalnya karena alasan keamanan), npm gagal menemukan metadata paket tersebut dan resolver mengembalikan null. Cara memastikan: lihat URL di field resolved di package-lock.json, lalu coba akses langsung di browser atau dengan npm view <package>@<version>.
Untuk mendiagnosis penyebab mana yang Anda alami, jalankan langkah-langkah berikut secara berurutan:
- Jalankan
npm cache verify→ jika ada corrupted entries, penyebabnya adalah cache. - Jalankan
npm ls --depth=0→ jika ada paketUNMET DEPENDENCYatauinvalid, penyebabnya adalahnode_modulesparsial atau lockfile tidak sinkron. - Cek
npm --versiondanlockfileVersiondipackage-lock.json→ jika tidak cocok, penyebabnya adalah versi npm. - Jalankan
npm view <package>@<version>untuk paket yang dicurigai → jika 404, penyebabnya adalah paket yang di-unpublish.
Memperbaiki error ini
Bagian ini menyajikan langkah-langkah perbaikan dari yang paling minim destruktif hingga yang paling radikal. Ikuti urutannya—seringkali langkah pertama sudah cukup.
Langkah 1: Bersihkan cache npm
Perintah ini menghapus semua entri cache yang korup dan memaksa npm mengunduh paket dari registry secara fresh:
npm cache clean --force
Output yang diharapkan:
npm WARN using --force Recommended modifications: disabling force
npm cache clean --force
npm info it worked if it ends with ok
Kemudian verifikasi cache sudah bersih:
npm cache verify
Output yang diharapkan:
Cache verified and compressed (~XX MB)
Content verified: XXXX entries
Corrupted: 0
Pastikan angka Corrupted adalah 0. Setelah itu, jalankan kembali npm install di proyek Anda. Jika berhasil tanpa error, maka penyebabnya memang cache yang korup, dan masalah sudah selesai.
Langkah 2: Hapus node_modules dan package-lock.json, lalu instal ulang
Jika langkah 1 tidak menyelesaikan masalah, berikut perintah yang menghapus kedua artefak sekaligus:
rm -rf node_modules package-lock.json
npm install
Di Windows PowerShell, perintahnya sedikit berbeda:
Remove-Item -Recurse -Force node_modules
Remove-Item -Force package-lock.json
npm install
Output yang diharapkan dari npm install:
added 342 packages in 12s
42 packages are looking for funding
run `npm fund` for details
Jika Anda melihat output seperti di atas tanpa error Cannot read properties of null, berarti perbaikan berhasil. Verifikasi lebih lanjut dengan menjalankan:
npm ls --depth=0
Output harus menampilkan daftar paket tanpa ada label UNMET, invalid, atau ERR!.
Langkah 3: Gunakan npm ci untuk instalasi bersih
Jika proyek Anda menggunakan CI/CD pipeline dan error muncul di sana, npm ci adalah pilihan yang lebih tepat daripada npm install. Perintah ini menghapus node_modules secara otomatis dan menginstal berdasarkan package-lock.json secara eksak, tanpa mutasi:
npm ci
Output yang diharapkan:
npm WARN config global `--global`, `--local` are deprecated. Use `--location`
removed 1 package in 2s
added 342 packages in 8s
Perhatikan bahwa npm ci mensyaratkan package-lock.json sudah ada. Jika lockfile tidak ada, npm ci akan error dengan pesan berbeda. Jadi pastikan lockfile sudah ter-generate sebelumnya (minimal sekali npm install berhasil di lokal).
Langkah 4: Sinkronkan versi npm
Jika Anda menemukan ketidakcocokan versi npm (misalnya lockfile lockfileVersion: 3 tetapi Anda pakai npm v6), langkah permanennya adalah menstandarkan versi npm di seluruh tim:
npm install -g npm@latest
Atau, jika proyek membutuhkan versi spesifik:
npm install -g npm@8
Setelah itu, regenerate lockfile:
rm -rf node_modules package-lock.json
npm install
Ini memastikan lockfile di-generate oleh versi npm yang sama dengan yang digunakan untuk membacanya, mengeliminasi ketidakcocokan format.
Verifikasi solusi berhasil
Setelah menjalankan langkah-langkah di atas, verifikasi secara menyeluruh:
# Pastikan tidak ada error saat instalasi
npm install
# Pastikan dependency tree sehat
npm ls
# Pastikan proyek bisa dijalankan
npm start # atau npm run dev, sesuai script Anda
Jika ketiga perintah di atas berjalan tanpa error, masalah sudah terpecahkan secara permanen untuk kondisi saat ini.
Solusi jangka panjang
Memperbaiki error sekali bukan berarti error itu tidak akan kembali. Berikut adalah konfigurasi dan best practice yang secara sistematis mencegah error Cannot read properties of null (reading 'package') muncul kembali.
Gunakan .npmrc untuk mengontrol perilaku cache dan resolusi
Buat atau edit file .npmrc di root proyek Anda:
# Paksa npm untuk selalu validasi integritas paket
strict-ssl=true
# Tingkatkan timeout untuk koneksi lambat (mencegah download parsial)
fetch-timeout=60000
fetch-retry-mintimeout=20000
fetch-retry-maxtimeout=120000
# Pastikan paket diambil dari registry resmi
registry=https://registry.npmjs.org/
Konfigurasi fetch-timeout dan retry di atas sangat penting untuk koneksi di Indonesia yang sering tidak stabil. Banyak kasus cache korup terjadi karena koneksi terputus di tengah unduhan, menyebabkan paket tersimpan secara parsial di cache. Dengan timeout yang lebih longgar dan retry yang lebih agresif, kemungkinan unduhan parsial berkurang drastis.
Standarisasi versi npm dengan engines di package.json
Tambahkan field engines untuk memaksa seluruh anggota tim menggunakan versi npm yang sama:
{
"name": "my-project",
"version": "1.0.0",
"engines": {
"node": ">=18.0.0",
"npm": ">=9.0.0"
},
"scripts": {
"preinstall": "node -e \"if(process.env.npm_package_engines_npm && !require('semver').satisfies(require('child_process').execSync('npm -v').toString().trim(), process.env.npm_package_engines_npm)) { console.error('Wrong npm version'); process.exit(1); }\""
}
}
Atau cara yang lebih sederhana dan banyak dipakai: gunakan paket only-allow:
{
"scripts": {
"preinstall": "npx only-allow npm"
}
}
Selalu commit package-lock.json
Ini mungkin terlihat obvious, tetapi banyak proyek—terutama proyek kecil—masih memasukkan package-lock.json ke .gitignore. Tanpa lockfile yang ter-commit, setiap npm install di mesin berbeda bisa menghasilkan pohon dependensi yang berbeda, dan salah satu resolusi itu bisa merujuk ke paket yang sudah di-unpublish atau versi yang breaking. Pastikan .gitignore Anda tidak mengandung package-lock.json.
# Cek apakah lockfile di-ignore
git check-ignore package-lock.json
Jika output menunjukkan file tersebut di-ignore, hapus entri tersebut dari .gitignore, lalu commit lockfile:
git add package-lock.json
git commit -m "chore: commit package-lock.json for reproducible builds"
Perbedaan antar OS
Masalah ini bisa lebih sering muncul di Windows karena beberapa alasan spesifik:
- Path length limit. Windows memiliki batas path 260 karakter secara default.
node_modulesyang dalam bisa melebihinya, menyebabkan file tertulis secara parsial atau gagal dibaca, yang kemudian memicu null reference. Solusinya: aktifkan long path di Windows:
# Jalankan sebagai Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
-Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
Lalu konfigurasi git untuk mendukung long path:
git config --global core.longpaths true
Case sensitivity. Windows filesystem tidak case-sensitive, sedangkan npm package names bisa berbeda hanya karena case (misalnya
lodashvsLodash). Ini bisa menyebabkan npm melihat dua entry yang seharusnya sama sebagai berbeda, merusak resolusi. Solusinya: selalu gunakan nama paket persis seperti yang tertera di registry.Line ending (CRLF vs LF). Meskipun tidak langsung menyebabkan error ini, line ending yang berbeda bisa merusak integrity hash di lockfile, yang kemudian memicu npm menganggap paket korup. Gunakan
.gitattributes:
* text=auto eol=lf
Di Linux dan macOS, masalah path length dan case sensitivity umumnya tidak ada, sehingga error ini lebih jarang muncul di environment tersebut. Namun, cache korup bisa terjadi di semua OS—jadi langkah-langkah pembersihan cache tetap relevan.
Troubleshooting lanjutan
Jika semua solusi di atas sudah Anda jalankan tetapi error masih muncul, saatnya masuk ke level diagnosis yang lebih dalam.
Baca log npm secara detail
npm menyimpan log lengkap setiap kali perintah dijalankan. Lokasi log selalu dicantumkan di output error:
npm ERR! A complete log of this run can be found in:
npm ERR! /home/username/.npm/_logs/2024-11-15T08_32_14_567Z-debug-0.log
Buka file log tersebut:
cat /home/username/.npm/_logs/2024-11-15T08_32_14_567Z-debug-0.log
Atau di Windows:
Get-Content "$env:USERPROFILE\.npm\_logs\2024-11-15T08_32_14_567Z-debug-0.log"
Di dalam log, cari baris yang mengandung kata null atau Cannot read properties. Perhatikan stack trace di bawahnya—stack trace akan menunjukkan file npm mana yang melempar error, dan seringkali juga menunjukkan nama paket mana yang gagal di-resolve. Misalnya:
55 verbose stack TypeError: Cannot read properties of null (reading 'package')
55 verbose stack at Arborist.[node] (/usr/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/build-ideal-tree.js:123:45)
55 verbose stack at async Arborist.buildIdealTree (/usr/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/build-ideal-tree.js:55:20)
Dari trace di atas, Anda tahu bahwa masalahnya ada di arborist—modul resolver dependensi npm. Ini mengonfirmasi bahwa masalahnya bukan di kode Anda, melainkan di bagaimana npm membangun pohon dependensi.
Gunakan --loglevel silly untuk output maksimal
Jika log file tidak cukup informatif, jalankan ulang perintah dengan log level paling verbose:
npm install --loglevel silly 2>&1 | tee npm-install-debug.log
Flag --loglevel silly membuat npm mencetak setiap langkah resolusi, termasuk paket mana yang sedang diproses ketika error terjadi. File npm-install-debug.log menyimpan output sehingga bisa dianalisis kemudian. Cari baris terakhir sebelum error muncul—itu biasanya menunjukkan paket spesifik yang bermasalah.
Periksa secara manual paket yang dicurigai
Jika dari log Anda mengidentifikasi paket tertentu (misalnya some-package@1.2.3), periksa apakah paket itu masih ada di registry:
npm view some-package@1.2.3
Jika outputnya 404 Not Found, paket tersebut sudah di-unpublish atau versinya tidak pernah eksis. Solusinya: update ke versi yang tersedia:
npm view some-package versions --json
Lalu pilih versi yang tersedia dan update package.json Anda:
npm install some-package@<versi-yang-tersedia>
Downgrade atau upgrade npm
Dalam beberapa kasus yang langka, error ini adalah bug di npm itu sendiri. Cek apakah versi npm Anda memiliki known bug dengan melihat changelog atau issue tracker npm. Sebagai workaround sementara:
# Upgrade ke versi terbaru
npm install -g npm@latest
# Atau downgrade ke versi stable sebelumnya
npm install -g npm@10
Setelah mengganti versi npm, ulangi proses instalasi dari awal (hapus node_modules dan package-lock.json terlebih dahulu).
Gunakan package manager alternatif sebagai isolasi
Jika npm Anda benar-benar stuck dan proyek harus jalan sekarang, Anda bisa mencoba Yarn atau pnpm sebagai alternatif sementara. Keduanya membaca package.json yang sama tetapi menggunakan mekanisme resolusi yang berbeda:
# Menggunakan Yarn
corepack enable
yarn install
# Menggunakan pnpm
corepack enable
pnpm install
Perhatikan bahwa lockfile Yarn (yarn.lock) dan pnpm (pnpm-lock.yaml) berbeda dari package-lock.json. Jangan commit lockfile alternatif ini ke repository jika tidak direncanakan—ini hanya untuk isolasi apakah masalahnya spesifik di npm atau lebih luas.
Sumber resmi untuk deep-dive
Untuk pemahaman yang lebih mendalam tentang mekanisme internal npm yang memicu error ini, referensi berikut sangat direkomendasikan:
- npm documentation — arborist: https://github.com/npm/arborist — Arborist adalah modul yang menangani resolusi dependensi di npm v7+. Memahami cara kerjanya membantu Anda tahu kenapa
nullbisa muncul di pohon dependensi. - npm CLI documentation: https://docs.npmjs.com/ — Dokumentasi resmi untuk semua flag dan konfigurasi npm, termasuk
npm cachedannpm ci. - npm GitHub Issues: https://github.com/npm/cli/issues — Cari issue dengan keyword
"Cannot read properties of null reading package". Banyak issue yang sudah di-resolve di versi npm tertentu, dan Anda bisa menemukan workaround yang spesifik untuk versi Anda. - Node.js best practices repository: https://github.com/goldbergyoni/nodebestpractices — Panduan komprehensif tentang best practice di ekosistem Node.js, termasuk manajemen dependensi.
Dengan pemahaman yang mendalam tentang mekanisme di balik error ini, Anda tidak hanya bisa memperbaikinya tetapi juga mencegahnya—dan error-error serupa lainnya—di masa depan. Kunci utamanya adalah menjaga integritas tiga komponen: cache npm, node_modules, dan package-lock.json. Selama ketiganya dalam kondisi konsisten dan sehat, resolver npm tidak akan pernah mengembalikan null untuk objek paket yang seharusnya eksis.