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 memberi jawaban yang buruk (atau memutus koneksi), 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 tidak punya tempat untuk diproses.

• 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.

• Perubahan firewall atau jaringan antara proxy dan origin. Misalnya, CDN tidak lagi bisa menjangkau origin yang alamat IP atau aturan firewall-nya berubah.

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. Alat HTTP Headers dari DNS Robot meminta halaman dari server kami dan menampilkan kode status yang tepat. Jika kami juga mendapat 502, masalahnya di situs, bukan di Anda. Ping Test menunjukkan apakah mesin server merespons sama sekali.

• Hard reload dan hapus cache. Ctrl + Shift + R (Mac: Cmd + Shift + R) melewati salinan cache, kalau-kalau yang ditampilkan kepada Anda adalah halaman error lama.

• 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 hampir selalu mencatat persis apa yang salah. Kerjakan empat pemeriksaan ini secara berurutan.

1. Baca Log Error Proxy

Munculkan lagi error 502-nya, lalu baca baris-baris terakhir log error di server proxy:

# 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

Pesan-pesan nginx berikut mencakup sebagian besar kasus 502, dan masing-masing menunjuk ke solusinya:

2. Pastikan Aplikasi Upstream Berjalan

# PHP-FPM (sesuaikan versinya)
sudo systemctl status php8.3-fpm
sudo journalctl -u php8.3-fpm -n 50

# Node.js di bawah PM2
pm2 status
pm2 logs --lines 50

# Docker
docker ps -a          # cari container yang terus-menerus restart
docker logs --tail 50 <container>

# Apakah dihentikan karena memakai terlalu banyak memori?
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:

# Ke mana nginx meneruskan permintaan?
grep -rn "proxy_pass\|fastcgi_pass" /etc/nginx/sites-enabled/

# Apa yang benar-benar sedang mendengarkan?
sudo ss -tlnp            # port TCP dan prosesnya
ls -l /run/php/          # file socket PHP-FPM

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). Setelah perubahan apa pun, jalankan sudo nginx -t dan sudo systemctl reload nginx.

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:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_buffer_size 16k;        # ruang untuk header besar (sebelumnya default 4k)
    proxy_buffers 4 32k;
    proxy_busy_buffers_size 64k;
}

Setelah nginx -t dan reload, halaman itu kembali mengembalikan 200. Pelajarannya: jika hanya sebagian halaman yang mengembalikan 502 sementara bagian lain situs berfungsi, cari batasan ukuran, seperti header besar atau 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 (server.keepAliveTimeout, di Node.js 26 dan sebelumnya), 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)
// Harus lebih panjang dari idle timeout load balancer (default ALB: 60 dtk)
server.keepAliveTimeout = 65_000
server.headersTimeout = 66_000 // sedikit di atas keepAliveTimeout

502 Bad Gateway di Cloudflare

Di belakang Cloudflare, pertama lihat dulu siapa yang membuat halaman error-nya:

• Halaman bermerek Cloudflare (Browser ✓ / Cloudflare ✓ / Host ✗): Cloudflare berfungsi tetapi tidak mendapat respons valid dari server origin Anda. Pastikan origin menyala, mendengarkan di 443/80, dan firewall-nya tidak memblokir rentang IP Cloudflare. Uji origin secara langsung dengan Port Checker.

• Halaman 502 polos tanpa merek: jika tidak menyebut cloudflare (misalnya menyebut nginx atau Apache), server origin Anda sendiri yang menghasilkan 502. Pakai langkah-langkah sisi server di atas. Halaman kosong dengan hanya tulisan "cloudflare" di bagian bawah berasal dari Cloudflare sendiri, misalnya saat pengalihan lalu lintas singkat atau saat origin mengirim konten gzip yang rusak.

• IP origin berubah? Jika Anda pindah hosting, perbarui A record di DNS Cloudflare. DNS Lookup menunjukkan apa yang saat ini dilihat dunia.

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.