Cara Mengatasi Error Nginx 502 Bad Gateway dan PHP-FPM Timeout pada Server Laravel

Gejala & Diagnosis Eror Nginx 502 Bad Gateway pada Laravel

Kesalahan HTTP 502 Bad Gateway pada server Laravel terjadi ketika web server Nginx gagal menerima respon yang valid dari pemroses backend PHP-FPM (FastCGI Process Manager). Hal ini paling sering dipicu oleh skrip Laravel yang mengalami eksekusi melebihi batas waktu (timeout), konsumsi memori melampaui limit, atau worker PHP-FPM yang mengalami crash akibat beban tinggi.

Berikut adalah 4 akar penyebab (root cause) teknis utama:

• Timeout Konfigurasi FastCGI: Nginx memutuskan koneksi karena PHP-FPM belum menyelesaikan eksekusi dalam batas `fastcgi_read_timeout` default (biasanya 60 detik).
• Alokasi Memori PHP-FPM Habis: Skrip seperti ekspor Excel/PDF besar atau pemrosesan gambar memicu Fatal Error: Allowed memory size exhausted.
• Kapasitas Worker PHP-FPM Penuh: Parameter pm.max_children terlalu kecil sehingga antrean request baru ditolak oleh PHP-FPM.
• Hak Akses Socket File Mismatch: Nginx tidak memiliki permission untuk membaca UNIX socket file /run/php/php8.2-fpm.sock.

“Solusi Nginx 502 Bad Gateway harus menyelaraskan tiga tingkat konfigurasi: batas waktu Nginx FastCGI, batas waktu eksekusi PHP-FPM, dan optimasi pemrosesan latar belakang Laravel Queue.” — Tim DevOps & Web Engineer AN Media Jember

Langkah 1: Cek Log Kesalahan Real-Time di Level Server & Laravel

Sebelum mengubah konfigurasi, lakukan isolasi masalah dengan mengecek log kesalahan berikut melalui SSH/Terminal:

# Cek log kesalahan Nginx
sudo tail -f -n 50 /var/log/nginx/error.log

# Cek log kesalahan PHP-FPM
sudo tail -f -n 50 /var/log/php8.2-fpm.log

# Cek log exception Laravel
tail -f -n 50 storage/logs/laravel.log

Jika pada log Nginx ditemukan pesan upstream timed out (110: Connection timed out) while reading response header from upstream, maka akar masalahnya adalah PHP-FPM Timeout.

Langkah 2: Tingkatkan Batas Waktu (Timeout) pada Nginx Server Block

Buka file konfigurasi blok situs Nginx Anda (misalnya /etc/nginx/sites-available/domain.com):

sudo nano /etc/nginx/sites-available/domain.com

Tambahkan directive timeout pada blok location ~ \.php$:

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    
    # Tambahkan parameter timeout berikut (dalam detik)
    fastcgi_read_timeout 300;
    fastcgi_send_timeout 300;
    fastcgi_connect_timeout 300;
    fastcgi_buffer_size 128k;
    fastcgi_buffers 4 256k;
    fastcgi_busy_buffers_size 256k;
}

Langkah 3: Sesuaikan Batas Waktu & Memori pada Pool PHP-FPM & php.ini

Buka file konfigurasi pool PHP-FPM (misalnya /etc/php/8.2/fpm/pool.d/www.conf):

sudo nano /etc/php/8.2/fpm/pool.d/www.conf

Cari dan ubah directive request_terminate_timeout:

request_terminate_timeout = 300s

Selanjutnya, perbarui file php.ini PHP-FPM (/etc/php/8.2/fpm/php.ini):

max_execution_time = 300
max_input_time = 300
memory_limit = 512M

Langkah 4: Optimasi Process Manager (PM) Worker PHP-FPM

Jika server menerima trafik simultan yang tinggi, tingkatkan jumlah worker PHP-FPM pada /etc/php/8.2/fpm/pool.d/www.conf:

pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
pm.max_requests = 500

Langkah 5: Pindahkan Pemrosesan Berat ke Laravel Queue Worker

Jangan menjalankan proses panjang (seperti kirim email massal atau generate laporan PDF) secara synchronous di HTTP request. Gunakan Laravel Queue:

# Buat tabel job queue di Laravel
php artisan queue:table
php artisan migrate

# Jalankan worker di background (atau gunakan Supervisor)
php artisan queue:work --timeout=300 --tries=3

Langkah 6: Validasi Sintaks & Reload Service

Setelah seluruh konfigurasi diperbarui, jalankan pengujian sintaks Nginx dan restart service:

# Pengujian sintaks Nginx
sudo nginx -t

# Restart PHP-FPM & Nginx
sudo systemctl restart php8.2-fpm
sudo systemctl restart nginx

Rangkuman Checklist Pemecahan Masalah 502 Bad Gateway

• Inspeksi log /var/log/nginx/error.log & storage/logs/laravel.log.
• Setel fastcgi_read_timeout 300; pada Nginx location block.
• Setel request_terminate_timeout = 300s & memory_limit = 512M pada PHP-FPM.
• Naikkan pm.max_children jika worker PHP-FPM habis.
• Gunakan Laravel Queue dengan Supervisor untuk pemrosesan latar belakang.

Kesimpulan & Support Infrastructure AN Media

Penerapan batas waktu dan manajemen worker yang presisi pada Nginx & PHP-FPM memastikan aplikasi Laravel Anda tetap stabil dan responsif di lingkungan produksi. Jika bisnis Anda memerlukan Jasa Deployment, Tuning Server & Maintenance Laravel di Jember, tim engineer AN Media siap membantu 24/7.