502 Bad Gateway Nginx: Artinya Apa & Cara Mengatasinya

Pernah melihat pesan 502 Bad Gateway Nginx saat membuka website? Sederhananya, 502 Bad Gateway Nginx artinya Nginx gagal mendapatkan respons yang valid dari server aplikasi di belakangnya. Di artikel ini, kamu akan memahami penyebab, cara diagnosis, hingga langkah mengatasinya.

Apa Artinya 502 Bad Gateway Nginx?

Nginx bukan hanya web server. Dalam banyak konfigurasi, Nginx juga bertindak sebagai reverse proxy, yaitu perantara antara browser pengguna dan server aplikasi atau backend.

Alurnya kira-kira seperti ini: browser mengirim request → Nginx menerima request → Nginx meneruskannya ke upstream → upstream memproses request → respons dikirim kembali melalui Nginx ke browser.

Masalah muncul ketika Nginx tidak bisa terhubung ke upstream atau menerima respons yang valid. Kondisi inilah yang kemudian ditampilkan sebagai error 502 bad gateway. Dengan kata lain, HTTP status code 502 menunjukkan adanya masalah komunikasi antara gateway/proxy dan server di belakangnya.

Misalnya, kamu menjalankan aplikasi Node.js di port 3000 dan Nginx dikonfigurasi untuk meneruskan request ke 127.0.0.1:3000. Kalau aplikasi Node.js berhenti, port tersebut tidak lagi menerima koneksi. Nginx tetap menerima request dari pengunjung, tetapi tidak mendapatkan respons dari aplikasi sehingga 502 muncul.

Hal yang sama bisa terjadi pada PHP-FPM, Gunicorn, Apache, Docker container, maupun microservice.

Karena tampilannya mirip dengan 503 Service Unavailable atau 504 Gateway Timeout, jangan buru-buru menganggap semua error tersebut sama. Root cause-nya bisa berbeda, sehingga diagnosis berdasarkan log menjadi langkah penting.

Langkah Pertama: Cek Nginx Error Log

Sebelum mengubah konfigurasi atau melakukan restart server, biasakan cek Nginx error log terlebih dahulu:

sudo tail -n 100 /var/log/nginx/error.log

Log biasanya memberikan petunjuk paling jelas mengenai masalah upstream. Misalnya:

connect() failed (111: Connection refused)
while connecting to upstream

Kode seperti 111: Connection refused, 110: Connection timed out, atau 104: Connection reset by peer dapat membantu mengarahkan diagnosis. Bagian upstream juga menunjukkan server atau endpoint yang gagal diakses Nginx.

Kalau file error.log tidak tersedia atau kosong, Nginx bisa saja mencatat log melalui systemd journal. Coba:

sudo journalctl -u nginx -n 100

Dari sini, kamu tidak perlu menebak-nebak penyebab server error Nginx.

7 Penyebab 502 Bad Gateway Nginx

502 biasanya bukan muncul tanpa alasan. Ada beberapa penyebab yang cukup umum, terutama pada server yang menggunakan Nginx sebagai reverse proxy.

#1. Upstream Server Mati atau Tidak Bisa Diakses

Ini salah satu penyebab paling sederhana. Nginx berjalan normal, tetapi aplikasi di belakangnya berhenti.

Contohnya:

PHP-FPM tidak berjalan.
Aplikasi Node.js crash.
Gunicorn berhenti.
Docker container mati.
Microservice tidak merespons.

Dalam kondisi tersebut, Nginx tidak punya upstream yang bisa memberikan respons sehingga request berakhir dengan 502.

#2. Konfigurasi Upstream Salah

Kesalahan konfigurasi juga sering menjadi biang kerok.

Misalnya:

proxy_pass http://127.0.0.1:3001;

Padahal aplikasi sebenarnya berjalan di port 3000.

Kesalahan lain bisa berupa Unix socket yang salah, typo pada server block, atau socket yang tidak tersedia. Nginx akhirnya gagal membuat koneksi ke backend.

#3. Respons Upstream Terlalu Lambat

Aplikasi yang membutuhkan waktu lama untuk memproses request juga bisa menyebabkan masalah. Penyebabnya dapat berupa query database yang berat, API lambat, beban server tinggi, atau bottleneck pada kode aplikasi.

Kalau upstream tidak memberikan respons sesuai batas waktu yang ditentukan, koneksi dapat berakhir gagal.

#4. PHP-FPM atau Application Server Bermasalah

Pada website PHP, Nginx umumnya meneruskan request ke PHP-FPM.

Masalah dapat muncul ketika jumlah worker terlalu sedikit, konfigurasi pool tidak tepat, atau socket PHP-FPM tidak tersedia. Pada website dengan trafik tinggi, kapasitas worker yang tidak mencukupi juga dapat membuat request menumpuk.

#5. Resource Server Habis

Jangan lupa mengecek kondisi server. RAM yang habis dapat memicu OOM killer untuk menghentikan proses. CPU yang terlalu tinggi juga bisa membuat aplikasi terlambat merespons.

Selain itu, batas file descriptor atau process limit seperti ulimit dan max_children pada PHP-FPM dapat menghambat pembuatan koneksi baru. Dalam kondisi tertentu, Nginx worker process crash juga dapat menjadi indikasi bahwa server sedang mengalami tekanan resource atau masalah proses.

#6. Firewall atau Network Filtering

Firewall lokal seperti UFW atau iptables dapat memblokir port yang digunakan upstream. Pada lingkungan cloud, security group atau aturan jaringan juga bisa menjadi penyebab.

Jadi, jangan hanya memastikan aplikasinya hidup. Pastikan Nginx memang bisa berkomunikasi dengannya.

#7. DNS Tidak Bisa Resolve

Kalau proxy_pass menggunakan hostname, masalah DNS juga dapat menyebabkan 502.

Hal ini cukup mungkin terjadi pada lingkungan Docker, Kubernetes, atau konfigurasi /etc/hosts yang tidak tepat. Ketika hostname upstream tidak bisa diterjemahkan menjadi alamat IP, Nginx tidak tahu harus menghubungi server yang mana.

5 Langkah Diagnosis Error 502 Bad Gateway

Ketika website production tiba-tiba menampilkan 502, hindari langsung melakukan restart tanpa mencari penyebabnya. Gunakan urutan diagnosis berikut.

#1. Baca Error Log

Mulai dengan:

sudo tail -n 100 /var/log/nginx/error.log

Perhatikan kode error dan alamat upstream.

#2. Pastikan Upstream Berjalan

Cek apakah ada service yang sedang listen pada port tujuan:

sudo ss -tlnp | grep :3000

Ganti 3000 dengan port aplikasi yang kamu gunakan.

#3. Periksa Log Aplikasi

Kalau upstream berupa service systemd:

sudo journalctl -u myapp -n 200

Jika menggunakan Docker:

docker logs myapp --tail 200

Sering kali penyebab aplikasi crash justru terlihat jelas di sini.

#4. Test Upstream Secara Langsung

Coba akses backend tanpa melewati Nginx:

curl -v http://127.0.0.1:3000/health

Kalau request berhasil, kemungkinan masalah berada di antara Nginx dan upstream. Kalau gagal, kemungkinan besar aplikasi backend yang bermasalah.

#5. Test Konfigurasi Nginx

Setelah melakukan perubahan konfigurasi, jalankan:

sudo nginx -t

Jika konfigurasi valid, kamu bisa reload:

sudo systemctl reload nginx

Jangan lupa mengecek resource server menggunakan df -h, free -h, dan dmesg | tail -50 jika 502 muncul setelah deployment atau perubahan besar.

Cara Mengatasi 502 Bad Gateway Nginx

Setelah menemukan sumber masalah, solusi harus disesuaikan dengan penyebabnya.

Periksa konfigurasi Nginx. Pastikan alamat IP, port, hostname, dan socket upstream sudah benar.
Periksa koneksi jaringan. Pastikan firewall atau security rule tidak memblokir komunikasi antara Nginx dan backend.
Periksa SSL. Jika Nginx berkomunikasi dengan upstream melalui HTTPS, pastikan sertifikat masih valid dan konfigurasi SSL kompatibel.
Periksa DNS. Pastikan hostname upstream dapat di-resolve dengan benar. Jika memang diperlukan, penggunaan alamat IP dapat menjadi alternatif.
Periksa aplikasi. Lihat log backend untuk mencari bug, crash, atau konfigurasi yang menyebabkan aplikasi mengembalikan respons tidak valid.

Jika seluruh pemeriksaan sudah dilakukan dan konfigurasi benar, restart Nginx bisa menjadi langkah terakhir untuk memulihkan service. Namun, restart sebaiknya bukan solusi utama karena akar masalah tetap perlu ditemukan.

Tips Bypass 502 Bad Gateway di Nginx

Kalau website harus tetap bisa diakses sementara tim memperbaiki backend, ada beberapa pendekatan sementara.

Gunakan Cached Content
Nginx dapat menyajikan konten cache ketika upstream sedang tidak tersedia. Cara ini cocok untuk konten yang tidak harus selalu real-time.
Siapkan Backup Upstream
Untuk sistem yang membutuhkan availability tinggi, siapkan server upstream cadangan. Nginx dapat diarahkan ke backend alternatif ketika server utama bermasalah.
Gunakan CDN
CDN dapat membantu mendistribusikan trafik dan mengurangi beban server, terutama ketika 502 berkaitan dengan overload pada upstream.
Tampilkan Maintenance Page
Jika backend sedang diperbaiki, maintenance page lebih baik daripada membiarkan pengunjung terus melihat halaman error.

Tips Mencegah 502 Bad Gateway Nginx

Mencegah 502 bukan berarti membuat server tidak pernah error. Fokusnya adalah mengurangi kemungkinan error sekaligus mempercepat deteksi ketika masalah terjadi.

Beberapa langkah yang bisa kamu lakukan:

Sesuaikan timeout Nginx dengan karakter aplikasi.
Optimalkan aplikasi dan query database agar backend tidak lambat.
Pantau kesehatan Nginx, aplikasi, resource server, dan jaringan.
Update Nginx, aplikasi, serta dependency secara berkala.
Pastikan kapasitas server sesuai dengan beban website.

Monitoring juga penting. Kalau error baru diketahui setelah banyak pengunjung mengeluh, troubleshooting biasanya menjadi jauh lebih sulit.

Kesimpulan

Jadi, 502 Bad Gateway Nginx artinya Nginx gagal mendapatkan respons yang valid dari upstream server. Penyebabnya bisa sederhana seperti service yang mati atau port yang salah, tetapi bisa juga berkaitan dengan resource server, firewall, DNS, hingga aplikasi yang crash.

Kunci mengatasinya bukan sekadar restart Nginx. Biasakan cek Nginx error log, pastikan upstream aktif, uji koneksi secara langsung, dan periksa resource serta log aplikasi. Dengan alur diagnosis yang tepat, kamu bisa menemukan sumber masalah tanpa trial and error berlebihan.

Kalau kamu butuh performa server yang lebih stabil untuk menjalankan Nginx, terutama untuk website personal brand atau project yang mulai berkembang, menggunakan VPS Murah dari IDwebhost bisa jadi pilihan yang lebih fleksibel.

Dengan VPS, kamu punya kontrol penuh atas konfigurasi server, termasuk optimasi Nginx agar performanya lebih maksimal, tanpa terbatas seperti shared hosting.

Gas VPS, Bikin Nginx Makin Stabil!