Pengunjung membuka situs WordPress Anda dan yang muncul adalah 502 Bad Gateway. Berbeda dengan layar putih WordPress, 502 datang dari lapisan server: Nginx bertindak sebagai perantara, meneruskan permintaan PHP ke PHP-FPM, tetapi tidak mendapat jawaban yang valid.
Daftar Isi
Jawaban Singkat
Periksa tiga hal dalam urutan ini: (1) apakah PHP-FPM berjalan, (2) apakah alamat fastcgi_pass di konfigurasi Nginx cocok dengan listen di konfigurasi PHP-FPM, dan (3) apakah worker PHP-FPM habis. Sebagian besar kasus 502 selesai di salah satu dari tiga titik ini.
Memahami Rantai Nginx — PHP-FPM
Alurnya sederhana: browser → Nginx → PHP-FPM → WordPress. Nginx sendiri tidak mengeksekusi PHP; ia meneruskannya. Bila PHP-FPM mati, soketnya salah, atau semua worker sibuk, Nginx tidak punya respons untuk diteruskan — dan menjawab 502.
| Pesan di error log Nginx | Artinya |
|---|---|
| connect() failed / connection refused while connecting to upstream | PHP-FPM tidak berjalan atau alamat soket salah |
| upstream timed out | PHP-FPM berjalan tetapi proses terlalu lama (biasanya berujung 504, tapi akar masalahnya sama) |
| upstream sent too big header | Header respons terlalu besar untuk buffer FastCGI |
Persiapan
- Akses SSH ke VPS dan hak sudo.
- Ketahui versi PHP yang dipakai situs (contoh: 8.2 atau 8.3) — perintah di bawah memakai 8.3 sebagai contoh; sesuaikan.
- Backup konfigurasi Nginx dan pool PHP-FPM sebelum mengubahnya.
Langkah 1: Baca Error Log Terlebih Dahulu
Jangan menebak. Buka log sambil memuat ulang halaman yang 502:
sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u php8.3-fpm -n 100 --no-pagerBaris log yang menyebut upstream dan alamat soket adalah petunjuk paling berharga — catat alamat soket yang disebut di sana.
Langkah 2: Pastikan PHP-FPM Berjalan
sudo systemctl status php8.3-fpm
sudo systemctl restart php8.3-fpm
sudo systemctl restart nginxJika situs langsung hidup setelah restart, penyebabnya adalah worker yang macet atau layanan yang crash. Itu perbaikan darurat, bukan akar masalah — lanjutkan ke Langkah 4 agar tidak terulang.
Langkah 3: Cocokkan fastcgi_pass dengan listen
Ini penyebab klasik setelah upgrade PHP: nama soket berubah (misalnya dari php8.2 ke php8.3) tetapi konfigurasi Nginx tidak ikut diperbarui. Periksa kedua sisi:
grep -E 'listen|user|group' /etc/php/8.3/fpm/pool.d/*.conf
grep -rn 'fastcgi_pass' /etc/nginx/sites-enabled/Keduanya harus menunjuk alamat yang sama persis, misalnya sama-sama unix:/run/php/php8.3-fpm.sock atau sama-sama 127.0.0.1:9000. Bila berbeda, samakan di konfigurasi Nginx, lalu uji dan muat ulang:
sudo nginx -t
sudo systemctl reload nginxPeriksa juga kepemilikan soket: bila soket dimiliki pengguna lain dari pengguna yang menjalankan Nginx, izin akses bisa menggagalkan koneksi.
Langkah 4: Jika Worker Habis
Tanda-tandanya: 502 muncul saat trafik tinggi, lalu hilang sendiri, lalu kembali. Periksa log pool PHP-FPM untuk baris server reached pm.max_children. Bila ada:
- Hitung kebutuhan worker dari RAM yang tersedia dan rata-rata memori per proses PHP — menaikkan
pm.max_childrentanpa perhitungan dapat menghabiskan RAM. - Cari penyebab worker menggantung: plugin berat, kueri lambat, atau permintaan eksternal yang timeout.
- Pertimbangkan
pm.max_requestsagar worker didaur ulang secara berkala.
Langkah 5: Jika Header Terlalu Besar
Bila log menyebut upstream sent too big header — sering terjadi saat instal/update plugin yang menghasilkan header respons besar — naikkan buffer FastCGI secara bertahap di blok server Nginx:
fastcgi_buffer_size 32k;
fastcgi_buffers 8 32k;Uji konfigurasi dengan nginx -t, lalu reload. Naikkan bertahap, jangan langsung ke nilai besar, karena buffer memakan memori.
Verifikasi Hasil
Perbaikan berhasil bila halaman yang 502 kini memuat normal, log Nginx tidak lagi mencatat error upstream pada URL tersebut, dan status PHP-FPM menunjukkan active (running). Uji halaman depan, satu artikel, dan wp-admin — ketiganya melewati PHP-FPM.
Troubleshooting Lanjutan
| Situasi | Langkah berikutnya |
|---|---|
| 502 hanya di satu halaman | Periksa plugin/kueri halaman itu; kemungkinan proses menggantung, bukan konfigurasi |
| 502 setelah tiap restart hilang lalu kembali | Telusuri penyebab worker habis atau memori bocor di plugin |
| 502 di semua situs di server yang sama | Fokus ke layanan PHP-FPM dan konfigurasi global, bukan satu situs |
| 502 muncul bersama error Cloudflare 5xx | Perbaiki dulu 502 di origin; error Cloudflare sering hanya cerminan masalah origin |
FAQ
Apakah restart Nginx saja cukup?
Kadang cukup untuk meredakan gejala, tetapi bila PHP-FPM yang bermasalah, restart Nginx tanpa menyentuh PHP-FPM tidak akan memperbaiki apa pun.
Kenapa 502 muncul setelah upgrade PHP?
Karena nama layanan dan soket berubah mengikuti versi (misalnya php8.2-fpm menjadi php8.3-fpm), sementara konfigurasi Nginx masih menunjuk soket lama.
Apakah 502 berarti situs saya diretas?
Tidak. 502 adalah error komunikasi antar layanan server, bukan indikasi peretasan. Fokuskan diagnosis ke PHP-FPM dan konfigurasi Nginx.
Kesimpulan
Diagnosis 502 yang baik selalu dimulai dari log, bukan dari restart membabi buta. Pastikan PHP-FPM berjalan, cocokkan fastcgi_pass dengan listen, atasi worker yang habis, dan sesuaikan buffer bila header menjadi masalah. Dengan urutan itu, sebagian besar 502 di WordPress Nginx selesai tanpa perlu menebak.