Saat deploy aplikasi Next.js ke hosting cPanel / CloudLinux, kadang website bisa menampilkan error:

503 Service Unavailable

Salah satu penyebab yang cukup umum adalah aplikasi Next.js berjalan dalam mode development, bukan mode production.

Pada Next.js versi baru, mode development dapat menggunakan Turbopack. Masalahnya, pada beberapa hosting cPanel berbasis CloudLinux, folder node_modules biasanya berupa symlink ke folder Node.js environment.

Contohnya seperti ini:

public_html/next/node_modules -> /home/user/nodevenv/public_html/next/24/lib/node_modules

Dalam kondisi tertentu, Turbopack bisa gagal membaca node_modules karena symlink tersebut mengarah keluar dari folder project.

Contoh error yang biasanya muncul di stderr.log:

Symlink [project]/node_modules is invalid, it points out of the filesystem root

Untuk mengatasi masalah ini, solusi yang bisa digunakan adalah menjalankan Next.js dalam mode production melalui file server.js.

1. Buat File server.js

Buat file bernama server.js di folder project Next.js.

Contoh lokasi file:

public_html/next/server.js

Isi file tersebut dengan kode berikut:

https://pastebin.com/raw/wEUjXPMx

2. Kenapa Harus Menggunakan NODE_ENV=production?

Bagian penting dari kode di atas adalah:

process.env.NODE_ENV = process.env.NODE_ENV || ‘production’
const dev = false

Kode tersebut memastikan bahwa aplikasi Next.js berjalan sebagai production server.

Jika NODE_ENV tidak diset ke production, beberapa hosting bisa menjalankan aplikasi dalam mode default atau development. Akibatnya, Next.js dapat menganggap aplikasi sedang berjalan dalam mode development.

Jika mode development aktif, Turbopack bisa ikut aktif. Pada hosting CloudLinux, hal ini dapat menyebabkan crash karena folder node_modules berupa symlink.

Dengan menggunakan:

const dev = false

Next.js akan dipaksa berjalan menggunakan build production, bukan development server.

3. Atur Script di package.json

Pastikan file package.json memiliki script seperti berikut:

{
“scripts”: {
“build”: “next build”,
“start”: “node server.js”
}
}

Setelah itu, jalankan build terlebih dahulu:

npm run build

Build ini wajib dilakukan agar Next.js memiliki hasil production yang siap dijalankan.

4. Setting di cPanel Node.js App

Masuk ke menu Setup Node.js App di cPanel, lalu sesuaikan pengaturannya seperti berikut:

Application root: public_html/next
Application startup file: server.js
Application mode: production

Jika tersedia pilihan command, gunakan salah satu dari berikut:

npm run start

atau:

node server.js

5. Restart Aplikasi

Setelah file server.js dibuat atau diubah, restart aplikasi dari menu Setup Node.js App di cPanel.

Kesimpulan

Error 503 Service Unavailable pada Next.js di cPanel / CloudLinux sering terjadi karena aplikasi berjalan sebagai development server, bukan production server.

Pada hosting CloudLinux, folder node_modules sering berupa symlink. Jika Next.js masuk ke mode development dan Turbopack aktif, proses aplikasi bisa gagal karena Turbopack tidak bisa membaca symlink tersebut dengan benar.

Solusi paling aman untuk website live adalah menjalankan Next.js dalam mode production menggunakan server.js.

Bagian penting yang perlu dipastikan adalah:

process.env.NODE_ENV = process.env.NODE_ENV || ‘production’
const dev = false

Dengan konfigurasi tersebut, Next.js akan menggunakan build production dan tidak masuk ke jalur development Turbopack yang dapat menyebabkan error symlink.