Cara Mengatasi Next Dev Error Mulai dari Log Terminal dan Penyebabnya

Ditulis oleh Next.js

Cara mengatasi next dev error paling cepat adalah membaca log terminal dulu, bukan langsung mengedit kode. Hentikan server, pastikan port 3000 bebas, lalu jalankan ulang npm run dev. Kalau error masih muncul setelah ganti ENV atau pindah branch, hapus folder .next dan restart. Sebagian besar error dev di App Router berasal dari lima hal: port bentrok, cache rusak, ENV belum terbaca, import salah, dan browser API dipakai di Server Component.

Penyebab Umum Next Dev Error di App Router

Overlay merah di browser hanya menampilkan akibat. Penyebab aslinya hampir selalu tertulis di terminal tempat npm run dev berjalan. Periksa nama file, nomor baris, dan baris pertama pesan error sebelum mengubah apapun.

Kelompokkan dulu masalahnya:

  • Port bentrok: biasanya muncul saat terminal lama belum dimatikan lalu terminal baru menjalankan dev server lagi.
  • Cache .next rusak: gejalanya error aneh setelah update dependency, pindah branch, atau proses dev berhenti paksa.
  • ENV hilang: variabel belum ada di .env.local atau nilainya berubah tetapi server belum direstart.
  • Import salah: path alias keliru, huruf besar kecil tidak cocok, atau file dipindah tanpa update import.
  • Browser API di Server Component: window, document, localStorage, event handler, atau hook seperti useState dipakai di file tanpa use client.
Masalah Penyebab Solusi cepat
Port already in use Proses dev lama masih jalan Matikan proses lama, jalankan ulang dev
Module not found Import atau path salah Perbaiki path dan nama file
ENV undefined Server belum restart Restart npm run dev
window is not defined Browser API di server Pindah ke Client Component atau beri guard
Error hilang-timbul Cache .next rusak Hapus .next, jalankan ulang

BACA JUGA:

Cara Memperbaiki Next Dev Error Langkah per Langkah

Ikuti urutan ini supaya tidak merusak kode yang sebenarnya sudah benar.

  1. Hentikan dev server dengan Ctrl+C. Periksa apakah port masih dipakai proses lain.
  2. Hapus cache .next hanya bila error tidak masuk akal atau muncul setelah perubahan besar.
  3. Periksa import, path file, dan ENV. Pastikan variabel server tidak dipanggil dari client tanpa prefix yang sesuai.
  4. Pisahkan kode server dan client. Pindahkan window, document, event, dan hook ke Client Component.
  5. Jalankan ulang npm run dev dan buka kembali route yang error.
# cek port 3000
lsof -i :3000

# hapus cache dev
rm -rf .next

# jalankan ulang
npm run dev

// guard browser API di Client Component
"use client";

if (typeof window !== "undefined") {
  localStorage.setItem("theme", "dark");
}

Validasi akhir:

  • Overlay error hilang dari browser.
  • Route yang sebelumnya gagal sekarang bisa dibuka dan direfresh.
  • HMR berjalan normal, perubahan kecil langsung tampil tanpa restart.

FAQ

Kenapa next dev error setelah ganti ENV?

Karena ENV dibaca saat proses dev mulai, jadi restart npm run dev setelah setiap perubahan ENV.

Apakah hapus folder .next aman?

Aman untuk development karena folder itu dibuat ulang otomatis setiap next dev berjalan.

Kapan cek Server Component dulu?

Segera cek saat error menyebut window, document, atau hook di file tanpa use client.

Artikel Terkait