Error 502 bad gateway nginx berarti Nginx berhasil menerima permintaan tetapi tidak mendapat jawaban yang sah dari proses di belakangnya — biasanya PHP-FPM, Node.js, atau aplikasi lain. Jadi yang bermasalah hampir selalu bukan Nginx, melainkan yang di belakangnya.
Salah paham yang paling umum soal 502 adalah menganggapnya masalah Nginx, lalu menghabiskan waktu memeriksa konfigurasi Nginx yang sebenarnya sudah benar.
Nginx di sini hanya perantara yang melaporkan bahwa ia tidak mendapat jawaban. Perbaikannya selalu di sisi yang seharusnya menjawab.
Cara baca log nginx supaya tidak menebak
Sebelum mengubah apa pun, satu perintah biasanya sudah menyebutkan penyebabnya. Cara baca log nginx yang tepat adalah melihat log error, bukan log akses.
Jalankan `tail -n 50 /var/log/nginx/error.log` tepat setelah 502 muncul. Baris yang relevan akan menyebutkan salah satu dari beberapa pola: `connect() to unix:/run/php/php8.2-fpm.sock failed` berarti PHP-FPM tidak berjalan atau soketnya salah. `upstream prematurely closed connection` berarti proses di belakang mati di tengah jalan. `upstream timed out` berarti ia masih bekerja tetapi terlalu lama.
Ketiga pesan itu mengarah ke tiga perbaikan yang berbeda. Menebak tanpa membaca log berarti mencoba ketiganya secara acak.
PHP-FPM mati atau soketnya tidak cocok
Kalau logmenyebut kegagalan koneksi ke soket, kemungkinan besar PHP-FPM mati atau alamat soketnya berbeda dari yang ditulis di konfigurasi Nginx.
Periksa dengan `systemctl status php8.2-fpm` — sesuaikan versinya. Kalau layanannya berhenti, `journalctl -u php8.2-fpm -n 50` biasanya menyebutkan alasannya: kesalahan sintaks di berkas konfigurasi, atau proses dimatikan sistem karena memori habis.
Ketidakcocokan soket sering terjadi setelah peningkatan versi PHP. Nginx masih menunjuk `php8.1-fpm.sock` sementara yang berjalan `php8.2-fpm.sock`. Pastikan nama di `fastcgi_pass` sama dengan `listen` di berkas pool PHP-FPM, lalu muat ulang keduanya.
Upstream timed out: aplikasi terlalu lama menjawab
Pesan upstream timed out berarti aplikasi Anda masih hidup tetapi tidak selesai dalam batas waktu yang ditetapkan Nginx. Bawaannya 60 detik.
Godaannya adalah menaikkan `fastcgi_read_timeout` sampai errornya hilang. Itu menyembunyikan gejala: permintaan yang butuh dua menit tetap merupakan masalah, dan sekarang ia menahan satu worker selama dua menit.
Yang sebaiknya dikerjakan: temukan permintaan mana yang lambat dari log akses dengan mencatat waktu respons, lalu perbaiki penyebabnya — biasanya kueri berat, panggilan ke layanan luar tanpa batas waktu, atau pemrosesan yang seharusnya berjalan di latar. Pekerjaan panjang seperti membuat laporan atau mengirim email massal memang tidak layak berjalan di dalam permintaan web.
Kehabisan proses PHP-FPM saat trafik naik
Ada satu pola yang khas: 502 hanya muncul pada jam sibuk, dan hilang sendiri setelahnya. Ini hampir selalu soal jumlah proses PHP-FPM yang tidak cukup.
Periksa log PHP-FPM untuk pesan tentang `max_children`. Bila ada, artinya semua proses sedang terpakai dan permintaan baru ditolak. Menaikkan `pm.max_children` menyelesaikannya — tetapi hanya bila memori mencukupi.
Cara menghitungnya sederhana: bagi memori yang tersedia untuk PHP dengan pemakaian rata-rata satu proses. Menaikkan angka melebihi itu hanya memindahkan masalah dari 502 menjadi sistem yang memakai swap, dan yang kedua lebih buruk.
502 muncul setelah deploy: tersangka yang berbeda
Kalau 502 muncul setelah deploy, penyebabnya biasanya bukan kapasitas melainkan sesuatu yang berubah. Daftar tersangkanya cukup pendek.
- Proses aplikasi belum dimulai ulang setelah kode diganti, sehingga ia memuat berkas yang sudah tidak ada.
- Ketergantungan baru belum terpasang di server, dan aplikasi gagal saat memuat.
- Berkas konfigurasi lingkungan belum disalin, sehingga koneksi basis data gagal.
- Izin berkas berubah, dan pengguna proses tidak bisa membaca kode atau menulis ke direktori cache.
- Versi runtime berbeda antara lingkungan pengembangan dan server.
Bedanya dengan error 500 internal server error
Membedakan keduanya mempersempit pencarian dengan cepat. Error 500 internal server error berarti aplikasi Anda berjalan dan menjawab, tetapi jawabannya berupa kesalahan — biasanya pengecualian di dalam kode.
Artinya untuk 500, tempat mencari adalah log aplikasi: log Laravel, log PHP, atau log framework yang Anda pakai. Untuk 502, tempat mencari adalah log Nginx dan log proses di belakangnya, karena aplikasinya bahkan tidak sempat menjawab.
Ada satu kasus yang membingungkan: kesalahan fatal PHP yang mematikan proses di tengah permintaan menghasilkan 502, bukan 500 — karena dari sudut pandang Nginx, sambungannya ditutup tanpa jawaban. Kalau 502 muncul hanya di satu halaman tertentu, curigai ini lebih dulu.
Mempersempit sumber masalah dengan cepat
Kalau log belum memberi jawaban jelas, beberapa pemeriksaan berikut mempersempit wilayahnya dalam beberapa menit.
Lewati Nginx sepenuhnya: panggil aplikasi langsung ke port atau soketnya dari dalam server. Kalau ia menjawab dengan benar, masalahnya di antara Nginx dan aplikasi — biasanya soket, izin, atau batas waktu. Kalau ia juga gagal, Nginx tidak perlu diperiksa lagi.
Periksa apakah 502 muncul di semua halaman atau hanya sebagian. Menyeluruh berarti prosesnya mati atau tidak terjangkau. Hanya di satu halaman berarti ada permintaan tertentu yang mematikan proses atau berjalan terlalu lama — dan halaman itulah yang perlu ditelusuri.
Terakhir, perhatikan polanya terhadap waktu. Muncul bersamaan dengan lonjakan trafik mengarah ke jumlah worker. Muncul pada jam yang sama setiap hari mengarah ke tugas terjadwal yang menghabiskan sumber daya. Muncul acak tanpa pola sering berarti kebocoran memori yang menumpuk sampai proses dimatikan sistem.
Kalau 502 sering terjadi dan penyebabnya sudah diketahui tetapi belum bisa segera diperbaiki, ada dua peredam sementara yang layak dipasang. Pertama, pemantauan proses yang memulai ulang layanan otomatis begitu ia mati — itu memotong durasi gangguan dari puluhan menit menjadi detik.
Kedua, batas sumber daya per proses supaya satu permintaan yang bermasalah tidak menghabiskan memori seluruh server. Keduanya tidak menyelesaikan penyebabnya, dan sebaiknya dicatat sebagai utang teknis dengan tenggat — bukan dianggap selesai.