Error Node.js di Panel Pterodactyl? Cara Mengatasi Versi Docker Image dan Modul Rusak

Kamu menekan Start, lalu Console langsung penuh tulisan merah dan aplikasimu berhenti sendiri. Error Node.js seperti ini sering terjadi di panel Pterodactyl, baik untuk bot (WhatsApp, Telegram, Discord), website, maupun API. Biasanya muncul setelah memakai script baru, memperbarui script, atau memindahkan project dari hosting lain. Kabar baiknya, penyebabnya hampir selalu satu dari dua hal: versi Node.js tidak cocok atau modul di folder node_modules rusak. Kamu tidak perlu jago coding untuk memperbaikinya.

Yang perlu disiapkan

• Akses login ke panel dan server yang bermasalah.
• Project atau script versi terbaru dari pembuatnya.
• Waktu sekitar 5 sampai 10 menit.

Kenapa aplikasi Node.js bisa error?

1. Versi Node.js tidak sesuai dengan project

Setiap project dibuat untuk versi Node.js tertentu. Misalnya script bot WhatsApp yang kamu pakai membutuhkan Node.js 24, tapi server memakai Node.js 20. Akibatnya, sebagian modul yang dibutuhkan gagal terpasang karena tidak cocok dengan versi Node.js yang berjalan. Aplikasi lalu crash dengan pesan seperti Cannot find module. Versi Node.js yang dipakai server ditentukan oleh Docker Image di tab Startup.

2. Modul di node_modules rusak atau tidak lengkap

Folder node_modules berisi semua modul yang dipakai aplikasi. Folder ini bisa rusak kalau upload tidak sempurna, koneksi internet putus saat pemasangan, atau modul terpasang di bawah versi Node.js yang salah.

Cara memperbaikinya, langkah demi langkah

Langkah 1: Samakan versi Node.js lewat Docker Image

1. Buka panel dan masuk ke servermu.
2. Buka tab Startup.
3. Cari bagian Docker Image.
4. Pilih versi Node.js yang sesuai rekomendasi pembuat project, misalnya Node.js 20 atau Node.js 24.

Belum tahu project kamu butuh versi berapa? Cek di file package.json, bagian "engines", atau baca README dan dokumentasinya. Pesan di Console seperti Unsupported engine atau EBADENGINE juga menunjukkan versi yang dibutuhkan.

Langkah 2: Hapus folder node_modules

Kalau versinya sudah pas tapi error masih muncul, kemungkinan modulnya rusak. Kita hapus supaya terpasang ulang dalam keadaan bersih.

1. Klik Stop dulu di tab Console kalau server masih menyala.
2. Buka tab Files.
3. Cari folder node_modules, ketuk menu titik tiga di sampingnya, lalu pilih Delete.

Penting: jangan hapus file package.json. File ini daftar modul yang akan dipasang ulang. Kalau terhapus, panel tidak tahu modul apa yang harus diunduh.

Langkah 3: Pasang ulang modul

Ada dua kemungkinan, tergantung egg yang kamu pakai.

Kalau egg mendukung auto-install: tidak ada yang perlu diubah. Kamu hanya perlu klik Start di tab Console. Folder node_modules akan muncul kembali otomatis. Tunggu sampai prosesnya selesai.

Kalau egg tidak mendukung auto-install dan Startup Command bisa kamu ubah:

1. Buka tab Startup, lalu cari Startup Command.
2. Ganti isinya sementara menjadi npm install (atau yarn install kalau project-mu memakai Yarn).
3. Buka tab Console, lalu klik Start.
4. Tunggu sampai muncul tulisan seperti added ... packages, atau server berhenti sendiri tanpa pesan error. Itu tandanya pemasangan selesai.

Proses ini bisa memakan beberapa menit. Jangan klik Kill kecuali server benar-benar tidak merespons.

Langkah 4: Jalankan lagi aplikasimu

Lewati langkah ini kalau kamu memakai auto-install dan tidak mengubah Startup Command.

1. Kembali ke tab Startup, lalu kembalikan Startup Command ke perintah asal, misalnya npm start (sesuaikan dengan project-mu).
2. Buka tab Console, lalu klik Start.
3. Aplikasimu seharusnya menyala normal. Contohnya bot WhatsApp mungkin meminta kamu memindai ulang kode QR yang muncul di konsol.

Contoh nyata: package butuh Node.js 20, tapi server memakai 18

Kasus ini sering terjadi pada project yang baru dipindah ke panel. Scriptnya butuh Node.js versi baru, tapi Docker Image server masih memakai versi lama. Salah satu contoh dari log asli:

Pesan seperti ini kita baca begini:

• Package yang bermasalah: chalk.
• Versi yang dibutuhkan: Node.js 20 ke atas.
• Versi yang dipakai server: 18.20.8.

Akibatnya instalasi module gagal atau tidak lengkap. Setelah itu program crash, dan sering berujung error Cannot find package karena package-nya memang tidak ikut terpasang.

Solusinya: naikkan versi Node.js lewat Docker Image, lalu hapus node_modules dan start ulang. Langkahnya ada di Cara Mengganti Versi Node.js (Docker Image).

Kalau error Cannot find module menunjuk ke file milikmu sendiri (path diawali ./), penyebabnya ada di kode, bukan di versi Node.js. Lihat Cara Mengatasi Error Cannot find module.

Masih error juga?

• Baca log di Console. Cari tulisan module not found atau Cannot find module. Artinya masih ada modul yang belum terpasang. Panduan lengkapnya ada di Mengatasi error "Cannot find module".
• Perbarui project. Versi lama bisa tidak cocok dengan Node.js atau layanan yang kamu pakai. Misalnya script bot WhatsApp lama bisa berhenti bekerja setelah sistem WhatsApp berubah, jadi pastikan memakai versi terbaru dari pembuatnya.
• Server berhenti sendiri berulang kali. Baca log dari baris paling atas dan lihat Menjalankan, menghentikan, dan merestart server.
• Tanya pembuat project. Kalau script berasal dari developer lain, mereka paling tahu versi Node.js dan modul yang dibutuhkan.
• Hubungi kami lewat halaman Kontak dan sertakan ID transaksi serta tangkapan layar konsol.

Pertanyaan yang sering muncul

Kenapa aplikasi yang tadinya jalan tiba-tiba error? Biasanya karena project diperbarui dan sekarang butuh versi Node.js yang lebih baru, atau karena modul rusak saat pemasangan ulang.

Apakah menghapus node_modules menghapus data aplikasi? Tidak. Folder itu hanya berisi modul yang bisa diunduh ulang. Tapi jangan menghapus file lain seperti package.json, file konfigurasi, atau folder sesi (misalnya sesi login bot WhatsApp).

Versi Node.js mana yang paling aman? Ikuti rekomendasi project-mu. Tidak ada satu versi yang cocok untuk semua aplikasi.