502 Bad Gateway: Arti dan Cara Mengatasinya

Apa Itu Error 502 Bad Gateway?

502 Bad Gateway adalah kode status HTTP yang berarti server yang menjawab Anda bertindak sebagai gateway atau proxy, dan server itu menerima respons tidak valid dari server di belakangnya. Standar HTTP (RFC 9110, bagian 15.6.3) mendefinisikannya persis seperti itu: server, "while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while attempting to fulfill the request."

Sebagian besar situs modern punya setidaknya dua lapisan. Server depan, seperti nginx, Apache, Cloudflare, atau load balancer cloud, menerima koneksi Anda, lalu meneruskan permintaan ke aplikasi upstream seperti PHP-FPM, aplikasi Node.js, Gunicorn milik Python, atau sebuah container. Ketika upstream itu mati, crash, atau menjawab dengan sesuatu yang tidak bisa dipakai proxy, proxy tidak punya apa-apa untuk diberikan kepada Anda, sehingga ia mengembalikan 502.

Poin pentingnya: gateway itu sendiri berfungsi. Ia menerima permintaan Anda dan merespons. Kesalahannya ada satu langkah lebih ke belakang.

Ragam Tampilan Error 502

Kode statusnya sama di mana-mana, tetapi halaman yang Anda lihat bergantung pada proxy mana yang membuatnya:

Versi mana pun yang Anda lihat, nama proxy di bagian bawah halaman adalah petunjuk berguna: nama itu memberi tahu pemilik situs lapisan mana yang harus diselidiki.

502 vs 500 vs 503 vs 504: Apa Bedanya?

Semua kode 5xx berarti "masalah server", tetapi masing-masing menunjuk ke lapisan yang berbeda:

Aturan cepatnya: 502 = upstream menolak koneksi, memutusnya, atau mengirim jawaban yang buruk, 504 = upstream tidak menjawab tepat waktu. Panduan kami untuk kode-kode tetangganya membahasnya secara mendalam: 500 Internal Server Error, 503 Service Unavailable, dan 504 Gateway Timeout.

Apa Penyebab 502 Bad Gateway?

• Aplikasi upstream tidak berjalan. PHP-FPM, Node, Gunicorn, atau container-nya crash, gagal start setelah deploy, atau sedang restart.
• Proxy mengarah ke tempat yang salah. proxy_pass atau fastcgi_pass memakai port yang salah, path socket PHP lama setelah upgrade, atau localhost di dalam container Docker.
• Aplikasi crash pada permintaan tertentu. Satu halaman memicu kill karena kehabisan memori atau exception yang tidak tertangani, dan koneksi tertutup sebelum ada respons.
• Semua worker sibuk. PHP-FPM mencapai pm.max_children, sehingga permintaan baru menunggu di antrean socket. Sebagian besar lalu timeout sebagai 504; begitu antrean penuh, nginx mencatat (11: Resource temporarily unavailable) dan mengembalikan 502.
• Header respons terlalu besar. Cookie besar atau header keamanan yang panjang melebihi proxy_buffer_size milik nginx.
• Keep-alive tidak cocok di belakang load balancer. Aplikasi menutup koneksi idle lebih cepat dari perkiraan load balancer, sehingga balancer mengirim permintaan ke koneksi yang sedang ditutup.
• Proxy tidak bisa menjangkau upstream setelah perubahan jaringan. Firewall yang menolak proxy, atau upstream yang pindah ke IP baru, menghasilkan 502 (Connection refused, No route to host). Firewall yang diam-diam membuang paket justru menghasilkan 504, dan di belakang Cloudflare keduanya tampil sebagai 521 atau 522.

Cara Mengatasi Error 502 sebagai Pengunjung

Anda tidak bisa memperbaiki server milik orang lain, tetapi langkah-langkah ini memastikan masalahnya memang di sisi mereka dan menyingkirkan penyebab lokal yang jarang terjadi:

• Tunggu 30 sampai 60 detik lalu muat ulang (Ctrl + R, atau Cmd + R di Mac). Banyak error 502 hanya berlangsung selama deploy atau restart.
• Cek apakah situs down untuk semua orang. Website Down Checker dari DNS Robot membuka halaman dari 11 lokasi, dan Cek HTTP Header menampilkan kode status persis yang diterima server kami. Jika mereka juga melihat 502, masalahnya di situs, bukan di Anda.
• Hard reload dengan Ctrl + Shift + R (Mac: Cmd + Shift + R), untuk kasus langka ketika halaman error dari cache yang ditampilkan kepada Anda.
• Flush DNS jika situs baru saja pindah hosting, agar Anda menjangkau server yang baru. Berikut cara flush DNS di semua sistem.
• Matikan VPN dan proxy. Proxy Anda sendiri bisa jadi "gateway" yang gagal, terutama di jaringan kantor.
• Coba browser lain atau ponsel dengan data seluler. Jika berhasil di sana, hapus cookie untuk situs itu.

Cara Mengatasi 502 Bad Gateway di Server Anda

Di sisi server, 502 termasuk error yang lebih mudah diperbaiki, karena proxy biasanya mencatat apa yang salah (pengecualiannya adalah race keep-alive pada load balancer dan 502 buatan Cloudflare sendiri). Kerjakan tiga pemeriksaan ini secara berurutan; bagian keempat adalah contoh nyata.

1. Baca Log Error Proxy

Munculkan lagi error 502-nya, lalu baca 50 baris terakhir log error proxy (perintahnya di bawah tabel). Setiap pesan nginx berikut menunjuk ke solusinya sendiri:

# nginx
sudo tail -n 50 /var/log/nginx/error.log

# Apache
sudo tail -n 50 /var/log/apache2/error.log    # Debian/Ubuntu
sudo tail -n 50 /var/log/httpd/error_log      # RHEL/Alma/Rocky

2. Pastikan Aplikasi Upstream Berjalan

# PHP-FPM (adjust the version)
sudo systemctl status php8.3-fpm
sudo journalctl -u php8.3-fpm -n 50

# Node.js under PM2
pm2 status
pm2 logs --lines 50

# Docker
docker ps -a          # look for containers that keep restarting
docker logs --tail 50 <container>

# Was it killed for using too much memory?
sudo dmesg -T | grep -i "killed process"

Jika layanannya berhenti, jalankan lagi dan cari tahu mengapa berhenti: deploy yang gagal, syntax error di rilis baru, atau OOM killer (out-of-memory killer). Di log PHP-FPM, server reached pm.max_children setting berarti semua worker sedang sibuk. Naikkan pm.max_children hanya jika server punya RAM yang cukup; jika tidak, cari permintaan lambat yang menyandera worker.

3. Pastikan proxy_pass Mengarah ke Port atau Socket yang Benar

Bandingkan tujuan yang diperintahkan ke nginx dengan apa yang benar-benar sedang mendengarkan:

# What is nginx proxying to?
sudo nginx -T 2>/dev/null | grep -n "proxy_pass\|fastcgi_pass"

# What is actually listening?
sudo ss -tlnp            # TCP ports and their processes
ls -l /run/php/          # PHP-FPM socket files

Dua ketidakcocokan klasik: setelah upgrade PHP, socket berubah menjadi php8.3-fpm.sock sementara nginx masih mengarah ke php8.1-fpm.sock; dan di dalam Docker, proxy_pass http://localhost:3000 mengarah ke container nginx itu sendiri, bukan ke aplikasi, jadi pakai nama service Compose (http://app:3000).

4. Contoh Nyata: Saat dnsrobot.net Menampilkan 502

Ini terjadi pada kami tanggal 30 September 2026. Setelah kami menerbitkan sekumpulan postingan blog baru, tepat satu di antaranya mengembalikan 502 Bad Gateway lewat nginx 1.24, sementara semua halaman lain berfungsi. Aplikasi Next.js di belakang nginx mengembalikan halaman yang sama dengan 200 OK saat kami memintanya langsung di port 3000. Jadi aplikasinya baik-baik saja dan gateway-lah yang gagal.

Log error nginx memuat jawabannya dalam satu baris: upstream sent too big header while reading response header from upstream. Header respons halaman itu berjumlah 4.087 byte, sebagian besar berupa header Content-Security-Policy yang panjang ditambah header Link untuk preload. nginx membaca bagian pertama respons, termasuk semua header, ke dalam buffer yang diatur oleh proxy_buffer_size, yang secara default sebesar satu halaman memori: 4 KB di server kami. Ruang yang tersisa tinggal 9 byte, dan seluruh blok header, termasuk baris status, meluap dari buffer itu.

Solusinya tiga baris di blok location yang meneruskan permintaan ke aplikasi; setelah nginx -t dan reload, halaman itu mengembalikan 200:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_buffer_size 16k;        # room for large headers (was the 4k default)
    proxy_buffers 4 32k;
    proxy_busy_buffers_size 64k;
}

Pelajarannya: jika hanya sebagian halaman yang mengembalikan 502 sementara bagian lain situs berfungsi, cari batasan ukuran, seperti header besar atau nilai Set-Cookie besar di halaman-halaman itu, sebelum mencurigai aplikasinya.

Node.js di Belakang Load Balancer: 502 Acak

Jika Anda menjalankan Node.js di belakang AWS Application Load Balancer atau balancer serupa dan sesekali melihat 502 tanpa error di log aplikasi, periksa timeout keep-alive. Server HTTP Node menutup koneksi keep-alive yang idle setelah 5 detik secara default di Node 26 dan sebelumnya (server.keepAliveTimeout; Node 24.6 dan 22.19 menambahkan keepAliveTimeoutBuffer 1 detik di atasnya, dan rilis mayor berikutnya menaikkan default menjadi 65 detik), sementara AWS ALB menahan koneksi idle selama 60 detik. Sesekali balancer memakai ulang koneksi tepat saat Node menutupnya, dan permintaan itu kembali sebagai 502.

Solusinya adalah membuat timeout aplikasi lebih panjang daripada timeout balancer:

const server = app.listen(3000)
// Must be longer than the load balancer's idle timeout (ALB default: 60s)
server.keepAliveTimeout = 65_000
server.headersTimeout = 66_000 // only needed before Node 18; harmless later

502 Bad Gateway di Cloudflare

Di belakang Cloudflare, pertama lihat dulu siapa yang membuat halaman error-nya (panduan 502/504 Cloudflare):

• Halaman bermerek Cloudflare (Browser ✓ / Cloudflare ✓ / Host ✗): server origin Anda sendiri yang mengembalikan 502 atau 504 ke Cloudflare. Perbaiki di origin dengan langkah-langkah sisi server di atas. Jika Cloudflare sama sekali tidak bisa terhubung ke origin, Anda akan mendapat 521 atau 522, bukan 502.
• Halaman polos bertuliskan "502 Bad Gateway" dengan "cloudflare" di bawahnya: ini berasal dari Cloudflare sendiri. Dokumentasi Cloudflare menyebut dua penyebab: origin mengirim konten gzip yang rusak, atau konten gzip tanpa Content-Length yang diperbarui (matikan kompresi di origin untuk menguji), dan lonjakan lalu lintas mendadak di satu data center Cloudflare, yang hilang dengan sendirinya.
• Halaman yang menyebut nginx atau Apache: biasanya permintaan sampai ke server Anda tanpa melewati Cloudflare, karena record DNS tidak diproksi (awan abu-abu) atau Anda melihat origin secara langsung (kecuali sebuah Cache Rule mengaktifkan Origin error page pass-through).
• Pindah hosting? Perbarui A record origin di DNS Cloudflare (IP origin yang salah biasanya tampil sebagai 521, 522, atau 523). DNS Lookup hanya menampilkan origin untuk record awan abu-abu (hanya DNS); record yang diproksi menjawab dengan IP milik Cloudflare sendiri.

Apakah Error 502 Merusak SEO?

Gangguan singkat tidak. Dokumentasi Google menyebutkan bahwa error server 5xx membuat crawler-nya memperlambat crawling untuk sementara. Halaman yang sudah terindeks awalnya tetap ada di indeks, tetapi jika error terus berlanjut, Google pada akhirnya menghapus URL tersebut.

Jadi 502 yang berlangsung beberapa menit saat deploy tidak berbahaya. Error 502 di halaman penting yang berlangsung berhari-hari, atau yang muncul hilang-timbul selama berminggu-minggu, bisa mengurangi crawling dan menurunkan peringkat. Pantau URL-URL utama Anda, dan periksa laporan Statistik crawling (Crawl stats) di Search Console setelah setiap gangguan.