Penyebab Error 502 Bad Gateway dan Cara Mengatasinya

Error 502 Bad Gateway muncul ketika server perantara, biasanya Nginx atau CDN, sudah menerima permintaanmu tetapi gagal mendapat jawaban yang sah dari aplikasi di belakangnya.

Pentingnya memahami ini sederhana: 502 hampir tidak pernah berarti "Nginx rusak". Nginx hanya menyampaikan kabar buruk dari backend. Kalau kamu langsung me-restart semuanya, error mungkin hilang sebentar lalu kembali, dan penyebab aslinya tidak pernah ketemu. Jauh lebih cepat membaca satu baris log yang tepat.

502 dan 504, apa bedanya?

Keduanya dikirim oleh proxy, bukan oleh aplikasi. 502 Bad Gateway berarti proxy menerima jawaban yang tidak sah, koneksinya ditolak, atau koneksi terputus di tengah jalan. 504 Gateway Timeout berarti proxy menunggu terlalu lama dan menyerah. Bedanya penting karena arah penyelidikannya berbeda: 502 sering soal backend mati atau salah alamat, 504 soal backend yang lambat.

Kalau website memakai CDN, ada satu lapisan lagi. Halaman error dari CDN biasanya menyebut bahwa masalahnya ada di server asal (origin). Artinya CDN tidak bisa mendapat jawaban dari servermu, dan penyelidikan tetap dimulai di server. Peran CDN sebagai perantara dijelaskan di apa itu CDN.

Pesan log yang menunjuk penyebabnya

Langkah pertama selalu sama: buka log error Nginx dengan tail -n 50 /var/log/nginx/error.log atau lokasi log di konfigurasi situsmu, lalu cocokkan pesannya.

Backend mati atau salah alamat

Penyebab paling sering adalah aplikasi di belakang Nginx tidak berjalan. Cek dengan systemctl status php8.3-fpm (sesuaikan versi) atau nama layanan aplikasimu, misalnya service Node.js, Gunicorn, atau container Docker. Kalau statusnya gagal, journalctl -u namalayanan -n 50 biasanya menjelaskan kenapa.

Kalau layanan berjalan tapi Nginx tetap menolak terhubung, periksa alamatnya. Bandingkan nilai proxy_pass atau fastcgi_pass di konfigurasi Nginx dengan port yang benar-benar didengarkan aplikasi, yang bisa dilihat lewat ss -tulpn. Kesalahan klasik setelah upgrade PHP adalah konfigurasi Nginx masih menunjuk ke socket versi lama. Kesalahan lain: aplikasi hanya mendengarkan di alamat tertentu, sementara Nginx mencoba alamat lain.

Bagaimana kalau PHP-FPM kehabisan worker?

Situs PHP yang tiba-tiba 502 saat ramai sering disebabkan PHP-FPM kehabisan worker. Log PHP-FPM akan mencatat peringatan bahwa batas pm.max_children sudah tercapai. Permintaan baru antre, sebagian akhirnya gagal.

Menaikkan pm.max_children memang solusinya, tapi hitung dulu. Setiap worker memakai memori, jadi kalikan rata-rata memori per worker dengan jumlah worker dan pastikan masih ada sisa RAM untuk database dan sistem. Kalau tidak, server akan kehabisan memori dan OOM killer mulai mematikan proses, yang memicu 502 jenis lain. Pembahasan memori ada di swap di Linux untuk VPS kecil.

Cek juga batas memori dan waktu eksekusi skrip PHP. Skrip yang melampaui batas bisa membuat worker berhenti di tengah jalan, dan Nginx mencatatnya sebagai koneksi yang ditutup sebelum waktunya.

Timeout: kapan dinaikkan, kapan tidak?

Untuk 504, Nginx punya setelan seperti proxy_read_timeout dan fastcgi_read_timeout, yang nilai bawaannya 60 detik. Menaikkannya masuk akal untuk proses yang memang lama dan jarang, misalnya ekspor laporan besar di panel admin. Untuk halaman yang dibuka pengunjung biasa, menaikkan timeout hanya menutupi masalah: pengunjung tetap menunggu lama, dan worker tersandera lebih lama.

Lebih baik cari sumber lambatnya. Slow query log database sering menjadi petunjuk pertama, dan setelan yang paling berpengaruh dibahas di optimasi MySQL dan MariaDB. Proses berat sebaiknya dipindahkan ke antrean latar belakang agar halaman bisa menjawab cepat.

Firewall, header besar, dan penyebab yang jarang

Kalau backend berada di server lain, firewall bisa memblokir koneksi dari Nginx ke port aplikasi. Uji dari server Nginx dengan curl -v http://ip-backend:port. Kalau gagal tersambung, periksa aturan firewall di kedua sisi.

Pesan upstream sent too big header muncul ketika aplikasi mengirim header besar, misalnya cookie yang sangat banyak. Solusinya menambah ukuran buffer seperti fastcgi_buffer_size atau proxy_buffer_size, lalu menguji konfigurasi dengan nginx -t sebelum reload.

Untuk situs di belakang CDN, pastikan firewall server tidak memblokir alamat IP milik CDN dan sertifikat SSL di server asal masih berlaku bila CDN terhubung lewat HTTPS. Perintah yang dipakai di atas dirangkum di perintah Linux untuk mengelola server.