Mengatasi Error 502 Bad Gateway pada Nginx: Penyebab dan Solusinya

Error 502 Bad Gateway pada Nginx adalah salah satu pesan yang paling sering membuat pengelola website panik. Halaman yang tadinya normal tiba-tiba menampilkan tulisan 502 Bad Gateway, sementara pengunjung tidak bisa mengakses konten sama sekali. Bagi banyak orang, pertanyaan pertama yang muncul adalah apa arti error ini dan apakah masalahnya ada di Nginx, di server, atau di aplikasi yang berjalan di belakangnya.

Secara singkat, 502 Bad Gateway berarti Nginx sebagai reverse proxy menerima respons yang tidak valid dari server upstream, yaitu aplikasi atau layanan yang seharusnya memproses permintaan. Jadi, Nginx sendiri biasanya masih hidup dan bisa menerima koneksi. Masalahnya justru sering berada di lapisan berikutnya, seperti PHP-FPM, Node.js, Gunicorn, atau container aplikasi yang mati, lambat merespons, atau salah dikonfigurasi.

Artikel ini membahas penyebab umum error 502 pada Nginx dan langkah-langkah mengatasinya secara berurutan. Pendekatannya bukan sekadar menambal gejala, tetapi memastikan akar masalahnya benar-benar ditemukan agar error tidak muncul lagi keesokan harinya.

Apa Arti Error 502 Bad Gateway pada Nginx

Nginx bekerja sebagai perantara antara browser pengunjung dan aplikasi backend. Ketika pengunjung membuka sebuah halaman, Nginx meneruskan permintaan tersebut ke upstream melalui konfigurasi `proxy_pass`, lalu mengembalikan respons aplikasi ke browser. Jika upstream tidak merespons, memutus koneksi terlalu cepat, atau mengirim data yang tidak sesuai, Nginx akan mengembalikan status 502.

Status ini berbeda dengan 504 Gateway Timeout. Pada 502, Nginx menganggap respons dari upstream tidak valid atau koneksi gagal. Pada 504, Nginx sudah menunggu terlalu lama sampai batas waktu yang ditentukan habis. Keduanya sering muncul bersamaan ketika aplikasi kelebihan beban, tetapi penanganannya bisa berbeda. Definisi resmi status 5xx dan aturan respons HTTP dapat dilihat pada standar HTTP modern RFC 9110 yang menjadi acuan implementasi server modern.

Penting untuk dipahami bahwa error 502 bukan berarti domain atau DNS bermasalah. Jika DNS salah, browser biasanya menampilkan pesan lain seperti server not found. Error 502 justru menandakan bahwa permintaan sudah sampai ke server, tetapi rantai pemrosesannya terputus di bagian upstream.

Penyebab Umum Error 502 di Nginx

Sebelum mengubah konfigurasi, ada baiknya memahami penyebab yang paling sering terjadi. Sebagian besar kasus 502 di lapangan berasal dari beberapa kondisi berikut.

Layanan upstream mati atau crash

Penyebab paling umum adalah aplikasi backend berhenti berjalan. PHP-FPM bisa mati karena kehabisan memori, proses Node.js bisa crash karena exception yang tidak tertangani, dan container bisa berhenti karena health check gagal. Ketika upstream tidak mendengarkan pada port atau socket yang dituju Nginx, setiap permintaan akan langsung menghasilkan 502.

Timeout dan antrean koneksi yang penuh

Aplikasi yang lambat memproses permintaan dapat membuat antrean di PHP-FPM atau worker Node.js penuh. Jika batas waktu Nginx lebih pendek daripada waktu yang dibutuhkan aplikasi, Nginx akan menutup koneksi dan melaporkan 502. Kondisi ini sering terjadi pada jam sibuk atau saat ada lonjakan trafik.

Konfigurasi proxy_pass yang salah

Kesalahan penulisan alamat upstream, port yang tidak sesuai, atau socket yang tidak ada akan membuat Nginx tidak bisa menghubungi aplikasi. Perbedaan penggunaan `localhost` dan `127.0.0.1`, misalnya, bisa berpengaruh ketika aplikasi hanya mendengarkan pada IPv4. Konfigurasi yang berubah saat migrasi server juga sering meninggalkan alamat lama yang sudah tidak aktif.

Resource server habis

Memori, CPU, atau jumlah file descriptor yang habis dapat membuat proses upstream gagal membuat koneksi baru. Pada server kecil, swap yang penuh dan proses OOM killer yang mematikan aplikasi adalah skenario yang cukup umum. Gejala ini biasanya disertai load average yang tinggi dan log sistem yang mencatat proses dihentikan.

Langkah Mengatasi Error 502 Bad Gateway

Penanganan yang rapi dimulai dari pengumpulan bukti, bukan dari menebak. Ikuti urutan berikut agar waktu perbaikan lebih singkat.

1. Periksa log Nginx dan log aplikasi

Langkah pertama adalah membaca log. Di Debian atau Ubuntu, log error Nginx biasanya berada di `/var/log/nginx/error.log`. Cari baris yang menyebut `connect() failed`, `upstream prematurely closed connection`, atau `no live upstreams`. Pesan tersebut menunjukkan apakah masalahnya koneksi, timeout, atau respons yang terputus.

Setelah itu, periksa log aplikasi. Untuk PHP-FPM, lihat log pool dan log PHP. Untuk Node.js, periksa output proses atau log container. Sering kali log aplikasi memuat error sebenarnya, misalnya koneksi database gagal atau konfigurasi environment yang hilang.

2. Pastikan service upstream benar-benar berjalan

Periksa status layanan dengan perintah seperti `systemctl status php8.2-fpm` atau `systemctl status nginx`. Untuk aplikasi berbasis container, gunakan `docker ps` dan `docker logs`. Pastikan proses mendengarkan pada port yang benar dengan `ss -lntp` atau `netstat -lntp`.

Jika layanan mati, jangan langsung menyalakannya tanpa mengetahui penyebabnya. Cek log terakhir, konsumsi memori, dan apakah ada perubahan konfigurasi atau deployment terbaru. Menyalakan ulang layanan hanya akan menyembunyikan masalah jika penyebabnya belum diperbaiki.

3. Sesuaikan timeout dan buffer proxy

Jika log menunjukkan timeout, sesuaikan parameter seperti `proxy_connect_timeout`, `proxy_read_timeout`, dan `proxy_send_timeout`. Nilai yang terlalu kecil membuat Nginx menyerah terlalu cepat, sedangkan nilai yang terlalu besar dapat menahan koneksi dan menghabiskan worker. Sesuaikan dengan karakteristik aplikasi, bukan sekadar menaikkan angka tanpa alasan.

Untuk aplikasi yang mengirim respons besar, periksa juga `proxy_buffer_size` dan `proxy_buffers`. Respons yang melebihi buffer dapat memicu error upstream sent too big header. Jika aplikasi memakai FastCGI, parameter `fastcgi_read_timeout` dan `fastcgi_buffers` juga perlu diperiksa.

4. Periksa konfigurasi proxy_pass dan socket

Pastikan alamat upstream pada blok `location` sesuai dengan tempat aplikasi mendengarkan. Jika memakai Unix socket, pastikan path dan izin aksesnya benar. Jika memakai TCP, pastikan port terbuka dan tidak diblokir firewall internal. Uji konfigurasi dengan `nginx -t` sebelum melakukan reload agar kesalahan sintaks tidak memperparah keadaan.

Pada arsitektur yang lebih kompleks, permintaan sering melewati beberapa lapisan sebelum mencapai aplikasi. Artikel tentang apa itu API Gateway dan fungsinya dalam arsitektur backend dapat membantu memahami peran tiap lapisan, sehingga titik putusnya lebih mudah dilacak.

5. Pantau resource dan batasi beban

Periksa penggunaan memori, CPU, dan disk dengan `free -m`, `top`, atau `htop`. Jika proses upstream sering dimatikan karena kehabisan memori, pertimbangkan menambah RAM, mengatur ulang jumlah worker, atau membatasi konkurensi. Untuk aplikasi PHP, jumlah proses pada pool perlu disesuaikan dengan kapasitas server agar tidak saling berebut sumber daya.

Jika lonjakan trafik berasal dari bot atau serangan, penanganan resource saja tidak cukup. Terapkan rate limiting, blokir pola permintaan yang mencurigakan, dan perkuat konfigurasi server. Panduan cara mengamankan server dari serangan DDoS dan bot membahas langkah praktis yang bisa diterapkan di Nginx.

Mencegah Error 502 Muncul Kembali

Setelah layanan pulih, lakukan pencegahan agar masalah yang sama tidak terulang. Aktifkan monitoring uptime dan alert untuk status 5xx, pantau penggunaan memori serta jumlah worker, dan simpan log dengan retensi yang cukup. Dokumentasikan perubahan konfigurasi agar saat insiden berikutnya tim bisa membandingkan kondisi normal dengan kondisi bermasalah.

Terapkan juga proses deployment yang terkontrol. Uji konfigurasi Nginx sebelum reload, gunakan health check pada container, dan pastikan aplikasi memiliki mekanisme restart yang aman. Perubahan kecil seperti menaikkan batas memori atau memperbaiki koneksi database sering kali lebih efektif daripada menambah timeout berulang kali.

Kesimpulan

Error 502 Bad Gateway pada Nginx pada dasarnya adalah sinyal bahwa komunikasi antara Nginx dan aplikasi upstream terganggu. Penyebabnya bisa berupa layanan yang mati, timeout, konfigurasi proxy yang salah, atau sumber daya server yang habis. Dengan membaca log, memastikan service berjalan, menyesuaikan timeout secara terukur, dan memantau resource, akar masalah dapat ditemukan dengan lebih cepat.

Jangan memperlakukan 502 sebagai gangguan yang cukup di-reload. Setiap kemunculannya adalah petunjuk berharga tentang kondisi sistem. Jika ditangani secara sistematis, error ini bisa ditekan seminimal mungkin dan ketersediaan layanan tetap terjaga.

Foto sampul oleh David Pupăză di Unsplash.