Troubleshooting: Error 502 Bad Gateway di Helipod — Penyebab dan Solusi

Error 502 Bad Gateway adalah salah satu error yang paling sering muncul saat deploy aplikasi ke cloud. Error ini berarti reverse proxy (Traefik) menerima response yang tidak valid dari aplikasi kamu.

Artikel ini menjelaskan penyebab paling umum dan cara mengatasinya.

Apa itu Error 502?

Internet → Traefik (reverse proxy) → Container aplikasi kamu
                                  ↑
                          502 Bad Gateway
                    (response tidak valid dari container)

Traefik tidak bisa menghubungi aplikasi kamu, atau aplikasi mengembalikan response yang tidak sesuai harapan.

Penyebab Umum

1. Aplikasi Tidak Listen di 0.0.0.0

Gejala: Container berjalan, tapi 502 muncul.

Penyebab: Aplikasi hanya listen di localhost atau 127.0.0.1. Traefik tidak bisa mengakses dari luar container.

Solusi:

// ❌ Salah — hanya bisa diakses dari dalam container
app.listen(3000);

// ✅ Benar — bisa diakses dari luar container
app.listen(3000, '0.0.0.0');

# ❌ Salah
uvicorn main:app --host 127.0.0.1 --port 8000

# ✅ Benar
uvicorn main:app --host 0.0.0.0 --port 8000

// Laravel — tidak perlu konfigurasi tambahan
// PHP-FPM/FrankenPHP sudah listen di 0.0.0.0

2. Port yang Salah

Gejala: Aplikasi berjalan, tapi 502 muncul.

Penyebab: Aplikasi listen di port yang berbeda dari yang di-expose di Dockerfile.

Solusi:

# Pastikan port di EXPOSE sama dengan port di aplikasi
EXPOSE 3000
CMD ["node", "server.js"]

# Cek port yang digunakan aplikasi
# Di Helipod → tab Logs → cari baris "Listening on port xxx"

Pastikan:

• EXPOSE di Dockerfile = port yang dipakai aplikasi
• PORT environment variable (jika digunakan) = port yang dipakai aplikasi

3. Aplikasi Crash

Gejala: Container restart terus-menerus, 502 muncul.

Penyebab: Aplikasi crash saat startup.

Solusi:

1. Cek logs di tab Logs → cari error message
2. Common errors:
   • EADDRINUSE — port sudah dipakai process lain
   • MODULE_NOT_FOUND — dependency belum terinstall
   • SyntaxError — ada error di code
   • ECONNREFUSED — database tidak bisa diakses

4. Database Connection Failed

Gejala: Aplikasi start, tapi crash saat ada request.

Penyebab: Database URL salah atau database belum deployed.

Solusi:

# Pastikan DATABASE_URL benar
DATABASE_URL=postgresql://user:password@postgres-db:5432/myapp
                                                    ↑
                                            gunakan service name, bukan localhost

Perbedaan:

# ❌ Salah — localhost tidak bisa diakses dari container lain
DATABASE_URL=postgresql://user:pass@localhost:5432/myapp

# ✅ Benar — gunakan service name dari Helipod
DATABASE_URL=postgresql://user:pass@postgres-db:5432/myapp

5. Environment Variable Hilang

Gejala: Aplikasi crash dengan error seperti undefined atau Cannot read property.

Penyebab: Environment variable belum diatur di dashboard.

Solusi:

1. Buka tab Variables
2. Pastikan semua env vars yang dibutuhkan sudah diatur
3. Deploy ulang

6. Build Gagal tapi Container Berjalan

Gejala: Build logs menunjukkan error, tapi container tetap berjalan (dengan versi lama).

Penyebab: Deploy menggunakan versi sebelumnya yang masih valid.

Solusi:

1. Cek build logs di tab Deployments
2. Fix error di code
3. Push dan deploy ulang

Langkah Debugging

1. Cek Logs

Helipod Dashboard → pilih pod → tab Logs

Cari:

• Error messages
• Stack traces
• "Listening on port xxx"

2. Cek Status Container

Helipod Dashboard → pilih pod → tab Overview

Cek:

• Status: Running / Stopped / Crashing
• Restarts: jika tinggi, ada masalah
• CPU/Memory usage

3. Cek Build Logs

Helipod Dashboard → pilih pod → tab Deployments → klik build

Cek:

• Build errors
• Dependency installation
• Build warnings

4. Test dari Terminal

Helipod Dashboard → pilih pod → tab Terminal

# Cek port yang listening
netstat -tlnp

# Cek process
ps aux

# Test koneksi database
pg_isready -h postgres-db -p 5432

Quick Fix Checklist

• Aplikasi listen di 0.0.0.0 (bukan localhost)
• Port di EXPOSE = port yang dipakai aplikasi
• Environment variables sudah lengkap
• Database URL menggunakan service name (bukan localhost)
• Database service sudah deployed
• Build berhasil tanpa error
• Tidak ada crash saat startup

Masih Error?

Jika setelah fix semua di atas masih error:

1. Cek logs lengkap — paste ke support@helipod.id
2. Sertakan:
   • URL aplikasi
   • Error message dari logs
   • Build logs
   • Language/framework yang digunakan

Tim Helipod akan membantu debugging.

Kesimpulan

Error 502 Bad Gateway hampir selalu karena salah konfigurasi — bukan masalah infrastruktur. Dengan checklist di atas, kamu bisa fix 502 dalam hitungan menit.

Mulai deploy di helipod.io — tidak perlu kartu kredit.

Punya pertanyaan? Hubungi kami di support@helipod.id atau bergabung ke komunitas di hangar.helipod.io.