Empat Error Node, npm, Port, dan Git: Diagnosis yang Aman

Empat Error Node, npm, Port, dan Git: Diagnosis Sebelum Menjalankan “Solusi Satu Baris”

Pesan error yang panjang sering mendorong kita menyalin perintah pertama dari forum. Masalahnya, beberapa perintah populer hanya menyembunyikan penyebab, menghapus informasi penting, atau membuka kembali perilaku kriptografi lama.

Artikel ini memakai urutan yang lebih aman: baca gejala, kumpulkan bukti, perbaiki penyebab, baru bersihkan state jika memang perlu.

1. ERR_OSSL_EVP_UNSUPPORTED

Error ini banyak muncul ketika proyek lama dijalankan pada Node.js yang memakai OpenSSL 3. Penyebab umumnya adalah dependency yang masih meminta algoritma atau ukuran kunci yang tidak diizinkan oleh konfigurasi default OpenSSL 3.

Node.js menyediakan:

node --openssl-legacy-provider app.js

Namun dokumentasi rilis Node.js menyebut opsi tersebut sebagai temporary workaround, bukan solusi permanen. Legacy provider mengaktifkan kembali algoritma lama.

Diagnosis:

node --version
npm ls
npm outdated

Langkah perbaikan:

1. Pastikan versi Node sesuai dengan engines, .nvmrc, .node-version, atau dokumentasi proyek.
2. Cari dependency yang memicu algoritma lama.
3. Perbarui bundler atau dependency tersebut.
4. Jalankan test dan build tanpa --openssl-legacy-provider.

Gunakan legacy provider hanya sementara untuk membuka proyek lama sambil melakukan upgrade. Jangan menjadikannya konfigurasi production permanen tanpa memahami konsekuensinya.

Sumber: catatan rilis Node.js 17 tentang OpenSSL 3 dan dokumentasi CLI Node.js.

2. Module not found

Jangan langsung menghapus package-lock.json. Lockfile menyimpan versi dependency yang sudah dipilih dan membantu menghasilkan instalasi yang konsisten.

Periksa nama package dan jalur import:

npm ls nama-package
node -p "require.resolve('nama-package')"

Kemudian pilih tindakan berdasarkan situasi.

Jika repository memiliki lockfile dan Anda ingin instalasi bersih yang mengikuti lockfile:

Hapus hanya folder hasil instalasi, bukan lockfile.
PowerShell:
Remove-Item node_modules -Recurse -Force
npm ci

macOS/Linux:
rm -rf node_modules
npm ci

Jika package memang belum tercatat:

npm install nama-package

Jika memakai workspace/monorepo, jalankan perintah dari root workspace dan periksa apakah dependency dideklarasikan pada package yang benar.

Tentang cache: dokumentasi npm menjelaskan bahwa cache bersifat content-addressable dan melakukan verifikasi integritas. Membersihkan seluruh cache biasanya tidak diperlukan. Jalankan:

npm cache verify

npm cache clean --force baru masuk akal setelah ada bukti cache rusak atau untuk mengosongkan ruang. Sumber: dokumentasi npm cache.

3. EADDRINUSE: address already in use

Error ini berarti ada proses yang sedang mendengarkan pada port tersebut. Temukan prosesnya sebelum menghentikannya.

Windows:

Get-NetTCPConnection -LocalPort 3000 -State Listen |
Select-Object LocalAddress, LocalPort, OwningProcess

Get-Process -Id

Jika prosesnya memang server lama milik Anda:

Stop-Process -Id

macOS/Linux:

lsof -nP -iTCP:3000 -sTCP:LISTEN
ps -p -o pid,command
kill

Hindari langsung memakai kill -9 atau /F. Penghentian paksa tidak memberi proses kesempatan melakukan cleanup. Gunakan hanya jika penghentian normal gagal.

Alternatif lain adalah memilih port berbeda:

PORT=3001 npm start

Cara menetapkan environment variable berbeda di PowerShell:

$env:PORT = "3001"
npm start

4. Konflik merge Git

Konflik bukan file rusak. Git sedang meminta keputusan karena dua perubahan menyentuh bagian yang sama.

Mulai dengan:

git status
git diff --name-only --diff-filter=U

Marker konflik:

>>>>> feature

Edit file, pilih atau gabungkan perubahan yang benar, lalu jalankan test. Tambahkan hanya file yang sudah diperiksa:

git add path/to/resolved-file
git status
git commit

Hindari git add . jika working tree juga berisi perubahan yang tidak terkait. Hindari pula git checkout -- . atau reset destruktif karena dapat menghapus pekerjaan yang belum disimpan.

Jika ingin membatalkan proses merge tanpa membuang perubahan yang sudah ada sebelum merge:

git merge --abort

Checklist diagnosis singkat

Sebelum menjalankan perintah dari internet:

1. Catat pesan error lengkap dan command yang memicunya.
2. Periksa versi runtime dan package manager.
3. Periksa git status.
4. Identifikasi file, dependency, proses, atau port yang benar-benar terlibat.
5. Pilih tindakan paling sempit.
6. Jalankan test yang mereproduksi masalah.
7. Dokumentasikan penyebab, bukan hanya command yang kebetulan membuat error hilang.

Solusi yang baik bukan yang paling pendek. Solusi yang baik menghilangkan penyebab tanpa merusak state lain dan dapat dibuktikan dengan test.

Referensi

• Node.js 17 release notes: OpenSSL 3
• Node.js CLI: --openssl-legacy-provider
• npm cache documentation
• npm install documentation