Memecahkan Masalah Instalasi

Lingkungan kerja yang rapi pun bisa menghadapi kendala: terminal mendadak tidak mengenal node, instalasi package global ditolak karena izin, atau dua versi runtime saling menimpa tanpa kita sadari. Kabar baiknya, hampir semua masalah instalasi Node.js termasuk tiga pola yang sama, dan setiap pola meninggalkan jejak yang bisa dibaca dari pesan errornya. Chapter ini melatih kita membaca jejak itu, mendiagnosis tiga masalah paling umum, lalu menutup section dengan tabel diagnosis cepat untuk penggunaan jangka panjang.

Membaca Pesan Error dengan Tenang #

Pesan error bukan kegagalan — pesan error adalah laporan diagnosis. Langkah pertama setiap kali error muncul adalah membaca baris pertamanya dengan saksama, karena baris itu biasanya menyebut dua hal: program apa yang bersuara, dan apa yang dibutuhkannya. Shell bersuara lewat command not found, runtime Node.js bersuara lewat nama error seperti Error: ... berikut kode errornya, dan npm bersuara lewat npm ERR!.

Sebagai latihan aman, mari kita jalankan program kecil yang sengaja memicu error Node.js yang sesungguhnya. Program berikut mencoba membaca berkas daftar-tugas.json yang tidak kita sediakan:

import { readFile } from "node:fs/promises";

try {
  const isi = await readFile("daftar-tugas.json", "utf8");
  console.log(isi);
} catch (err) {
  console.error("Kode error:", err.code);
  console.error("Pesan error:", err.message);
  process.exit(1);
}

Output yang Dihasilkan:

Kode error: ENOENT
Pesan error: ENOENT: no such file or directory, open 'daftar-tugas.json'

Mari kita bedah cara program ini melaporkan kegagalannya:

1. Baris 3-4 (try { ... }): operasi baca berkas dibungkus blok try supaya kegagalan bisa ditangkap oleh catch alih-alih menghentikan program begitu saja.
2. Baris 6-8 (catch (err)): object err membawa detail kegagalan. Property err.code berisi kode singkat yang stabil (ENOENT — no such entry), sedangkan err.message berisi kalimat lengkapnya. Kode ENOENT adalah bagian paling berharga: kode inilah yang kita cari di dokumentasi error Node.js saat butuh penjelasan resmi.
3. Baris 9 (process.exit(1)): program ditutup dengan kode status 1 — konvensi umum bahwa proses berakhir karena kegagalan. Kode status inilah yang dibaca oleh skrip otomatisasi untuk menilai sukses atau gagalnya sebuah perintah.

Pola yang sama berlaku untuk semua error Node.js: tangkap errornya, baca code dan message-nya, lalu putuskan tindakan berdasarkan keduanya — bukan berdasarkan tebakan.

Masalah 1: Perintah node Tidak Dikenali #

Gejala paling klasik terjadi saat terminal menolak perintah node. Bentuk pesannya bervariasi mengikuti shell yang dipakai:

# Linux / macOS dengan bash
bash: node: command not found

# macOS dengan zsh
zsh: command not found: node

# Windows Command Prompt
'node' is not recognized as an internal or external command, operable program or batch file.

Pesan seperti di atas bukan keluhan Node.js — shell-lah yang bersuara, karena shell tidak menemukan berkas node di direktori mana pun yang terdaftar pada PATH. Program kecil berikut meniru bentuk pesan tersebut sekaligus kode statusnya, sehingga kita bisa mengamatinya tanpa perlu benar-benar merusak instalasi:

// Simulasi pesan shell ketika perintah tidak ditemukan di PATH.
console.error("bash: node: command not found");
process.exit(127);

Output yang Dihasilkan:

bash: node: command not found

Angka 127 pada process.exit(127) bukan pilihan bebas — 127 adalah kode status yang dipakai shell ketika perintah tidak ditemukan. Penyebab paling umum dari masalah ini dan cara menanganinya:

• Terminal belum dibuka ulang setelah instalasi — PATH yang diperbarui hanya dibaca jendela terminal baru. Tutup dan buka kembali terminal.
• Opsi Add to PATH tidak tercentang saat instalasi di Windows — jalankan ulang installer, ubah pemasangan, lalu pastikan opsi tersebut aktif.
• Node.js memang belum terpasang — kembali ke Chapter Menginstal Node.js, lalu verifikasi dengan node --version.

Bila ketiganya sudah diperiksa, gunakan which node (Linux/macOS) atau where node (Windows) untuk melihat apakah shell menemukan node sama sekali, dan di lokasi mana.

Masalah 2: Izin Berkas Menolak Instalasi Global #

Gejala kedua muncul saat memasang package global (npm install -g) dan terminal membalas dengan EACCES: permission denied. Kode EACCES berarti sistem operasi menolak penulisan ke direktori tujuan — biasanya direktori milik sistem seperti /usr/local/lib yang dipakai npm ketika menginstal secara global tanpa versi manager.

sudo npm install -g sesuatu

Pilihan kedua itu selaras dengan materi Chapter Mengelola Versi Node.js: dengan nvm, perintah nvm install --lts memasang Node.js beserta seluruh direktori global npm di dalam folder rumah kita, jauh dari area yang dilindungi sistem operasi.

Masalah 3: Dua Versi Node.js Saling Menimpa #

Gejala ketiga paling senyap: semua perintah berjalan, tetapi node --version melaporkan versi yang tidak kita harapkan. Penyebabnya hampir selalu dua sumber instalasi berbeda — misalnya Node.js dari apt sekaligus dari nvm — yang sama-sama menyediakan berkas node. Shell memilih berkas pertama yang ditemukan sesuai urutan direktori di PATH, dan direktori itulah yang menang, terlepas dari niat kita.

Diagnosisnya dua langkah: jalankan which node untuk melihat lokasi berkas node yang aktif, lalu cocokkan dengan node --version. Bila lokasinya berada di direktori nvm tetapi versinya tidak sesuai, periksa apakah nvm use sudah dijalankan di sesi shell tersebut. Bila ternyata ada instalasi ganda, pilih satu sumber untuk dipertahankan dan lepas instalasi yang lain — memelihara dua sumber sekaligus hanya memperpanjang masalah ini.

Tabel Diagnosis Cepat #

Dengan tabel ini di tangan, gangguan instalasi tidak lagi berhenti di kata “gagal” — setiap gejala punya langkah pertama yang jelas. Persiapan lingkungan kita pun tuntas: Node.js terpasang, terverifikasi, dikenali shell, dan versinya terkelola. Saatnya masuk ke materi inti pemrograman: Section JavaScript untuk Node.js dimulai dari penyegaran variable dan scope — fondasi yang akan kita pakai di setiap baris kode berikutnya.