Server Solusi – Saat website menampilkan pesan 502 Bad Gateway, pengunjung tidak bisa mengakses halaman seperti biasanya. Masalah ini cukup membingungkan karena Nginx bisa saja masih berjalan normal, tetapi aplikasi di belakangnya justru tidak merespons dengan benar.

Pada konfigurasi reverse proxy, Nginx menerima permintaan dari pengunjung lalu meneruskannya ke aplikasi backend, misalnya PHP-FPM, Node.js, Apache, atau layanan API. Jika komunikasi dengan backend mengalami kegagalan, Nginx dapat mengembalikan respons HTTP 502.

Karena itu, cara mengatasi error 502 Bad Gateway Nginx yang tepat adalah memeriksa pesan error, koneksi ke backend, dan kondisi aplikasi sebelum mengubah konfigurasi atau melakukan restart layanan. Penyebab pastinya perlu ditentukan dari log dan kondisi server, bukan hanya dari halaman error yang muncul.

Apa Penyebab Error 502 Bad Gateway pada Nginx?

Error 502 menunjukkan bahwa gateway atau proxy menerima respons yang tidak valid dari server di belakangnya, atau gagal memperoleh respons yang valid sesuai kondisi kegagalan yang terjadi.

Beberapa penyebab yang perlu diperiksa meliputi:

• Service backend berhenti: PHP-FPM, Apache, Node.js, atau aplikasi lain tidak aktif.

• Port atau socket salah: Nginx meneruskan permintaan ke alamat, port, atau Unix socket yang tidak sesuai.

• Koneksi ditolak: Backend tidak menerima koneksi pada alamat tujuan.

• Aplikasi mengalami crash: Proses aplikasi berhenti atau menutup koneksi sebelum memberikan respons yang valid.

• Timeout: Backend terlalu lama memproses permintaan atau tidak mengirimkan data dalam batas waktu yang dikonfigurasi.

• Keterbatasan sumber daya: RAM, CPU, atau kapasitas proses tidak mencukupi sehingga backend terganggu.

• Kesalahan konfigurasi reverse proxy: Nilai proxy_pass atau konfigurasi upstream tidak sesuai dengan layanan tujuan.

Daftar tersebut merupakan kemungkinan penyebab, bukan bukti bahwa semuanya terjadi pada server kamu. Log Nginx dan log backend membantu mempersempit diagnosis. Dokumentasi resmi Nginx menjelaskan mekanisme proxy dan pengaturan timeout pada modul HTTP proxy.

1. Periksa Log Error Nginx Terlebih Dahulu

Sebelum mengubah konfigurasi, saya menyarankan kamu memulai dari log. Pesan di dalamnya sering memberikan petunjuk yang jauh lebih spesifik dibandingkan halaman 502 yang dilihat pengunjung.

Pada Ubuntu atau Debian dengan instalasi Nginx standar, lokasi log error umumnya berada di /var/log/nginx/error.log. Instalasi melalui Docker, panel hosting, atau konfigurasi khusus bisa menggunakan lokasi berbeda.

Jalankan:

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

Perintah ini menampilkan 100 baris terakhir log agar kamu bisa mencari pesan yang muncul saat error terjadi.

Jika kamu ingin memantau log secara langsung ketika mengakses website, gunakan:

sudo tail -f /var/log/nginx/error.log

Biarkan terminal terbuka, kemudian akses kembali URL yang bermasalah dari browser atau terminal lain. Tekan Ctrl+C untuk menghentikan pemantauan.

Perhatikan beberapa pesan berikut.

Pesan-pesan tersebut adalah contoh pola diagnosis, bukan hasil pengujian pada server kamu. Satu pesan pun belum tentu menjelaskan seluruh akar masalah, terutama ketika ada beberapa lapisan proxy.

2. Pastikan Service Nginx dan Backend Berjalan

Setelah menemukan petunjuk dari log, periksa status layanan yang terlibat. Nginx yang aktif tidak otomatis berarti aplikasi backend juga aktif.

Memeriksa status Nginx

Pada server Linux yang menggunakan systemd, jalankan:

sudo systemctl status nginx

Jika status menunjukkan active (running), proses Nginx sedang berjalan. Namun, hasil tersebut belum membuktikan bahwa Nginx dapat terhubung ke backend.

Jika Nginx tidak aktif, baca pesan status untuk mengetahui penyebabnya sebelum mencoba menyalakan ulang layanan. Dokumentasi Ubuntu juga menggunakan systemctl status nginx untuk memeriksa status service.

Memeriksa backend PHP-FPM

Jika website kamu menggunakan PHP-FPM, cari nama service yang tersedia:

systemctl list-units --type=service --all | grep -E 'php.*fpm'

Nama service dapat berbeda sesuai versi PHP dan distribusi Linux. Contohnya, service mungkin bernama php8.3-fpm, tetapi kamu tidak boleh menganggap versi tersebut pasti digunakan pada server kamu.

Setelah mengetahui nama yang benar, periksa statusnya. Misalnya:

sudo systemctl status php8.3-fpm

Ganti nama service tersebut sesuai hasil pemeriksaan.

Jika PHP-FPM tidak berjalan, periksa log service sebelum memulai ulang:

sudo journalctl -u php8.3-fpm -n 100 --no-pager

Apabila log menunjukkan kesalahan konfigurasi, kegagalan startup, atau masalah sumber daya, tangani penyebabnya terlebih dahulu. Menyalakan ulang service tanpa memahami error bisa membuat masalah yang sama terulang.

Memeriksa backend Node.js atau aplikasi lain

Untuk aplikasi yang dijalankan melalui systemd, periksa service aplikasi yang sebenarnya:

sudo systemctl status nama-aplikasi.service

Jika aplikasi menggunakan PM2, Docker, Supervisor, atau pengelola proses lain, gunakan alat yang sesuai dengan instalasi tersebut.

Jangan menjalankan perintah restart berdasarkan nama service contoh di atas sebelum memastikan service itu memang digunakan oleh website kamu.

3. Periksa Apakah Port Backend Bisa Diakses

Jika service terlihat aktif tetapi Nginx masih mengembalikan 502, langkah berikutnya adalah memastikan backend benar-benar menerima koneksi.

Misalnya, konfigurasi Nginx mengarah ke:

proxy_pass http://127.0.0.1:3000;

Artinya, Nginx mencoba meneruskan permintaan ke layanan HTTP pada alamat loopback 127.0.0.1 dan port 3000.

Periksa apakah ada proses yang mendengarkan pada port tersebut:

sudo ss -lntp

Untuk memfilter port tertentu:

sudo ss -lntp | grep ':3000'

Ganti 3000 dengan port backend yang benar.

Jika tidak ada proses yang mendengarkan pada port tujuan, periksa apakah aplikasi berjalan, apakah port yang digunakan sudah benar, dan apakah aplikasi hanya terikat ke alamat IP tertentu.

Jika port ditemukan, uji backend secara langsung:

curl -i --max-time 10 http://127.0.0.1:3000/

Perintah tersebut mencoba mengakses backend secara langsung dengan batas waktu 10 detik.

Cara membaca hasilnya:

• HTTP 200 atau respons HTTP lain: Backend memberikan respons. Periksa isi respons, endpoint, header, dan apakah Nginx meneruskan permintaan dengan benar. Respons selain 200 tidak otomatis berarti backend rusak.

• Connection refused: Tidak ada layanan yang menerima koneksi pada alamat dan port tersebut, atau koneksi ditolak.

• Connection timed out: Periksa apakah backend dapat dijangkau, aturan jaringan, dan kondisi aplikasi.

• HTTP 500: Backend merespons dengan kesalahan aplikasi. Periksa log backend.

• Tidak ada respons hingga batas waktu: Periksa proses aplikasi, beban server, dan apakah endpoint tersebut memang membutuhkan waktu pemrosesan panjang.

Perlu diingat, pengujian curl hanya membuktikan kondisi endpoint yang diuji pada saat itu. Hasilnya tidak menjamin semua endpoint website akan bekerja normal.

4. Periksa Konfigurasi proxy_pass dan Upstream

Kesalahan alamat backend merupakan salah satu hal penting yang perlu diperiksa ketika Nginx bertindak sebagai reverse proxy.

Lihat konfigurasi virtual host yang digunakan oleh domain kamu. Pada Ubuntu atau Debian, file konfigurasi situs sering berada di /etc/nginx/sites-available/, tetapi lokasi aktual dapat berbeda.

Periksa bagian yang berisi location, proxy_pass, atau deklarasi upstream.

Contoh konfigurasi reverse proxy yang sederhana:

server {listen 80;server_name example.com;location / {proxy_pass http://127.0.0.1:3000;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header X-Forwarded-Proto $scheme;}}

Catatan: example.com dan port 3000 merupakan nilai contoh. Gunakan konfigurasi ini hanya sebagai ilustrasi, bukan untuk mengganti seluruh konfigurasi situs yang sudah berjalan.

Periksa beberapa hal berikut:

1. Apakah alamat IP dan port sesuai dengan backend?

2. Apakah backend menggunakan HTTP atau HTTPS?

3. Apakah aplikasi mendengarkan pada alamat yang dapat dijangkau Nginx?

4. Apakah ada konfigurasi upstream yang menunjuk ke server lama atau port yang sudah berubah?

5. Apakah konfigurasi domain yang sedang diedit benar-benar digunakan oleh Nginx?

Dokumentasi Nginx menjelaskan bahwa proxy_pass menentukan server tujuan untuk permintaan yang diteruskan. Perbedaan protokol, alamat, dan konfigurasi upstream dapat memengaruhi koneksi ke backend.

Bagaimana jika backend menggunakan Unix socket?

PHP-FPM sering berkomunikasi melalui Unix socket, bukan port TCP. Contohnya, konfigurasi Nginx bisa berisi:

fastcgi_pass unix:/run/php/php8.3-fpm.sock;

Pastikan file socket yang dirujuk memang tersedia dan sesuai dengan konfigurasi PHP-FPM.

Periksa:

ls -l /run/php/

Jika socket tidak ditemukan, cari tahu apakah PHP-FPM aktif, apakah konfigurasi pool menggunakan path yang berbeda, atau apakah nama file socket berubah setelah pembaruan PHP.

Jika log menunjukkan Permission denied, periksa pengguna dan grup proses, izin direktori, serta aturan keamanan seperti AppArmor jika relevan. Hindari langsung menggunakan chmod 777 karena tindakan tersebut dapat membuka akses yang tidak diperlukan.

5. Periksa Timeout Jika Backend Terlalu Lama Merespons

Tidak semua error 502 disebabkan oleh backend yang mati. Dalam beberapa konfigurasi, masalah bisa muncul ketika proses backend mengalami keterlambatan atau menutup koneksi saat pemrosesan belum selesai.

Periksa error log untuk pesan seperti upstream timed out dan cocokkan waktunya dengan log aplikasi.

Jika aplikasi menggunakan Nginx sebagai reverse proxy, salah satu pengaturan yang relevan adalah:

location / {proxy_pass http://127.0.0.1:3000;proxy_connect_timeout 5s;proxy_send_timeout 60s;proxy_read_timeout 60s;}

Angka di atas hanya ilustrasi. Sesuaikan dengan kebutuhan aplikasi dan konfigurasi yang sudah ada. Jangan menyalin blok tersebut secara membabi buta ke konfigurasi produksi.

Perbedaan ketiga pengaturan tersebut:

• proxy_connect_timeout membatasi waktu untuk membangun koneksi ke server tujuan.

• proxy_send_timeout membatasi jeda waktu saat Nginx mengirimkan permintaan ke server tujuan.

• proxy_read_timeout membatasi jeda waktu antara dua operasi pembacaan berturut-turut dari server tujuan.

Khusus proxy_read_timeout, nilainya bukan batas total durasi sebuah permintaan dari awal hingga akhir. Pengaturan ini mengacu pada jeda antaroperasi pembacaan.

Jika aplikasi memerlukan waktu lebih lama, jangan langsung menaikkan semua timeout menjadi beberapa menit. Cari tahu mengapa pemrosesan melambat. Penyebabnya bisa berupa query database yang berat, API eksternal yang lambat, proses PHP yang kehabisan worker, atau keterbatasan CPU dan memori.

Timeout yang lebih besar hanya membantu pada kondisi tertentu dan tidak memperbaiki backend yang tidak sehat.

6. Periksa RAM, CPU, dan Kapasitas Server

Jika error muncul ketika website menerima banyak permintaan, periksa apakah sumber daya server mencukupi.

Jalankan:

free -h

Perintah ini menunjukkan penggunaan memori dan swap. Perhatikan ketersediaan memori serta perubahan penggunaannya ketika error terjadi.

Selanjutnya:

uptime

Perintah tersebut menampilkan waktu aktif server dan nilai load average. Nilai load average perlu dibaca sesuai jumlah CPU dan kondisi sistem; angka tinggi saja belum cukup untuk menyimpulkan bahwa server mengalami overload.

Untuk memeriksa ruang penyimpanan:

df -h

Partisi yang hampir penuh bisa mengganggu operasi aplikasi, penulisan log, atau layanan lain.

Jika menggunakan Linux dengan systemd, kamu juga dapat memeriksa pesan kernel terkait kemungkinan proses yang dihentikan karena kehabisan memori:

sudo journalctl -k --since "30 minutes ago" --no-pager

Cari pesan yang berkaitan dengan oom atau Out of memory, lalu cocokkan waktunya dengan kejadian error.

Apabila server menggunakan banyak aplikasi, periksa konsumsi sumber daya setiap service sebelum menaikkan kapasitas VPS. Tindakan seperti menambah worker PHP-FPM tanpa memperhitungkan RAM justru dapat memperburuk kondisi.

7. Validasi Konfigurasi Sebelum Reload Nginx

Jika diagnosis mengarah pada kesalahan konfigurasi, lakukan perubahan secukupnya dan simpan salinan konfigurasi sebelum mengedit file produksi.

Setelah selesai, jalankan:

sudo nginx -t

Perintah ini menguji sintaks konfigurasi dan memeriksa sejumlah file yang dirujuk. Jika pengujian gagal, jangan lanjutkan reload sebelum kesalahannya diperbaiki.

Jika hasil pengujian menyatakan konfigurasi valid, kamu dapat memuat ulang konfigurasi Nginx:

sudo systemctl reload nginx

Reload berbeda dari restart: reload meminta Nginx membaca ulang konfigurasi dan menerapkan perubahan secara bertahap. Namun, tetap perhatikan kondisi service, konfigurasi yang digunakan, dan dampak perubahan terhadap trafik produksi.

Setelah reload, periksa status layanan:

sudo systemctl status nginx

Kemudian, uji kembali website dan amati error log.

Jangan melakukan reload atau restart berulang kali tanpa memahami penyebab masalah. Jika error berasal dari PHP-FPM atau aplikasi backend, mengubah konfigurasi Nginx saja tidak akan menyelesaikannya.

8. Jika Menggunakan Apache di Belakang Nginx

Sebagian server menggunakan Nginx sebagai reverse proxy di depan Apache. Dalam konfigurasi seperti ini, Nginx menerima koneksi pengunjung lalu meneruskan permintaan ke Apache pada port tertentu.

Jika Apache berhenti atau port tujuan berubah, Nginx bisa gagal meneruskan permintaan.

Periksa status Apache:

sudo systemctl status apache2

Pada distribusi berbasis RHEL, nama servicenya sering berupa httpd, sehingga perintah pemeriksaannya menjadi:

sudo systemctl status httpd

Jika Apache aktif, periksa port yang sedang digunakan:

sudo ss -lntp

Cocokkan port tersebut dengan konfigurasi proxy_pass Nginx. Sebagai contoh, jika Nginx meneruskan permintaan ke 127.0.0.1:8080, pastikan Apache memang menerima koneksi pada alamat dan port tersebut.

Untuk memeriksa log Apache pada Ubuntu atau Debian, kamu dapat menggunakan:

sudo journalctl -u apache2 -n 100 --no-pager

Lokasi log Apache juga dapat ditentukan melalui konfigurasi instalasi yang digunakan.

Jika Apache tidak aktif, periksa penyebab kegagalannya sebelum mencoba menyalakannya kembali. Jika Apache aktif tetapi Nginx tidak dapat terhubung, periksa alamat listener, port, firewall, dan konfigurasi proxy.

9. Cara Memastikan Error 502 Sudah Teratasi

Setelah melakukan perbaikan, jangan hanya mengandalkan halaman website yang berhasil dibuka sekali. Lakukan beberapa pemeriksaan untuk memastikan komunikasi antara Nginx dan backend kembali berfungsi.

Uji respons HTTP dari server

Jalankan:

curl -sS -o /dev/null -w '%{http_code}\n' --max-time 15 https://example.com/

Ganti example.com dengan domain website kamu.

Perintah tersebut menampilkan kode status HTTP yang diterima dari URL yang diuji. Respons 200 biasanya menandakan halaman berhasil dilayani, sedangkan kode lain harus dinilai sesuai kebutuhan aplikasi. Redirect 301 atau 302, misalnya, belum tentu merupakan masalah.

Periksa log setelah pengujian

Jalankan:

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

Pastikan tidak ada error baru yang berkaitan dengan permintaan pengujian. Jika log menunjukkan error lain, lanjutkan diagnosis berdasarkan pesan terbaru.

Uji dari browser

Buka kembali website dari browser, kemudian periksa halaman utama dan endpoint yang sebelumnya bermasalah. Jika memungkinkan, uji juga proses yang membutuhkan backend, seperti login, pencarian, atau pemanggilan API.

Hasil yang diharapkan adalah Nginx dapat meneruskan permintaan ke backend dan pengunjung memperoleh respons sesuai fungsi aplikasi. Ini merupakan kriteria verifikasi yang perlu kamu uji sendiri, bukan hasil pengujian yang sudah dilakukan pada server tertentu.

10. Tips Mencegah Error 502 Terulang

Beberapa kebiasaan berikut membantu mengurangi risiko gangguan serupa.

• Pantau error log secara berkala. Perhatikan pesan baru yang muncul saat trafik meningkat atau setelah pembaruan aplikasi.

• Gunakan health check. Jika aplikasi mendukung endpoint kesehatan, pantau apakah backend benar-benar siap menerima permintaan.

• Validasi konfigurasi sebelum reload. Biasakan menjalankan nginx -t setiap kali mengubah konfigurasi.

• Simpan backup konfigurasi. Simpan salinan sebelum mengubah file virtual host, upstream, atau pengaturan PHP-FPM.

• Pantau sumber daya VPS. Perhatikan penggunaan RAM, CPU, disk, dan kapasitas worker aplikasi.

• Kelola timeout berdasarkan kebutuhan. Sesuaikan timeout setelah mengetahui karakteristik pemrosesan aplikasi, bukan sekadar untuk menyembunyikan error.

• Rencanakan pembaruan software. Periksa perubahan konfigurasi dan kompatibilitas service sebelum memperbarui PHP, Nginx, Apache, atau aplikasi.

• Hindari restart tanpa diagnosis. Restart dapat mengembalikan layanan sementara, tetapi tidak selalu menghilangkan akar masalah.

FAQ: Pertanyaan Seputar Error 502 Bad Gateway Nginx

1. Kenapa Nginx menampilkan 502 Bad Gateway padahal servicenya aktif?

Karena status aktif hanya menunjukkan proses Nginx berjalan. Backend yang dituju bisa saja berhenti, menggunakan port yang salah, menolak koneksi, mengalami timeout, atau mengirimkan respons yang tidak valid. Periksa error log Nginx dan uji backend secara langsung.

2. Apakah error 502 bisa diperbaiki dengan restart Nginx?

Bisa dalam kondisi tertentu, misalnya jika masalah berkaitan dengan konfigurasi yang perlu dimuat ulang. Namun, jika penyebabnya adalah PHP-FPM yang berhenti, aplikasi crash, atau koneksi backend yang salah, restart Nginx saja belum tentu membantu. Diagnosis tetap diperlukan.

3. Apa perbedaan error 502 dan 504 pada Nginx?

HTTP 502 menunjukkan bahwa gateway atau proxy mengalami masalah dalam memperoleh respons upstream yang valid. HTTP 504 menunjukkan bahwa gateway atau proxy tidak memperoleh respons tepat waktu dari upstream. Meski demikian, penyebab pastinya tetap perlu diperiksa melalui log dan konfigurasi.

4. Kenapa error 502 muncul hanya pada website tertentu?

Hal ini bisa terjadi karena konfigurasi virtual host, port backend, atau aplikasi untuk domain tersebut berbeda dari website lain di server yang sama. Periksa konfigurasi domain yang terdampak, deklarasi upstream, dan log yang sesuai dengan permintaan tersebut.

5. Apakah menaikkan proxy_read_timeout selalu menyelesaikan error 502?

Tidak. Pengaturan tersebut hanya relevan untuk kondisi tertentu yang melibatkan jeda pembacaan respons upstream. Jika backend tidak aktif, koneksi ditolak, atau aplikasi crash, menaikkan timeout tidak menyelesaikan akar masalah. Selain itu, timeout yang terlalu besar dapat membuat permintaan bermasalah bertahan lebih lama.

Kesimpulan

Cara mengatasi error 502 Bad Gateway Nginx sebaiknya dimulai dari pemeriksaan log, status backend, koneksi port atau socket, dan konfigurasi reverse proxy. Jika masalah berkaitan dengan timeout atau keterbatasan sumber daya, periksa pula kondisi aplikasi dan server sebelum mengubah pengaturan.

Urutan ini membantu kamu menghindari perubahan konfigurasi yang tidak diperlukan. Setelah melakukan perbaikan, validasi konfigurasi, uji respons HTTP, dan periksa kembali log untuk memastikan tidak ada error baru.

Jika website masih menampilkan 502, fokuskan pemeriksaan pada pesan error yang muncul tepat ketika permintaan gagal. Informasi tersebut lebih berguna untuk menentukan langkah selanjutnya daripada mencoba berbagai solusi secara acak.