Error Umum #

Sebagian besar masalah Nginx di production jatuh ke dalam kategori error yang sama berulang kali. Mengenali pola ini membuat diagnosis jauh lebih cepat — daripada mulai dari nol setiap kali, kamu bisa langsung ke kemungkinan penyebab yang paling sering.

502 Bad Gateway #

Nginx berhasil menerima request dari klien, tapi gagal mendapatkan response yang valid dari backend.

Penyebab paling umum:

1. Proses backend tidak berjalan
   Solusi: cek status proses
   → systemctl status nodejs / pm2 status / systemctl status php8.2-fpm

2. Backend berjalan di port yang berbeda dari yang dikonfigurasi di Nginx
   Solusi: verifikasi port
   → ss -tlnp | grep :3000

3. Backend mengembalikan response yang tidak valid
   Solusi: akses backend langsung tanpa Nginx
   → curl http://localhost:3000/api/health

4. Backend crash setelah menerima request tertentu
   Solusi: cek log backend, bukan hanya log Nginx
   → journalctl -u myapp -f

# Cek error log Nginx untuk detail
sudo tail -20 /var/log/nginx/error.log
# Cari: "connect() failed (111: Connection refused)"
# → backend tidak berjalan atau salah port

# Atau: "no live upstreams while connecting to upstream"
# → semua server di upstream block down

504 Gateway Timeout #

Nginx berhasil menghubungi backend, tapi backend tidak merespons dalam batas waktu yang dikonfigurasi.

Penyebab paling umum:

1. Backend lambat: query database berat, proses yang lama
   Solusi: identifikasi operasi yang lambat, optimalkan, atau naikkan timeout

2. Deadlock di database atau aplikasi
   Solusi: cek log backend untuk deadlock atau query yang hang

3. Timeout Nginx terlalu pendek untuk operasi yang memang butuh waktu lama
   Solusi: naikkan proxy_read_timeout untuk endpoint tertentu

# Naikkan timeout untuk endpoint yang memang butuh waktu lama
location /api/generate-report {
    proxy_pass http://backend;
    proxy_read_timeout 300s;   # 5 menit untuk generate report
    proxy_send_timeout 300s;
}

# Untuk semua endpoint (hati-hati: bisa menyembunyikan masalah performa)
# proxy_read_timeout 120s;

403 Forbidden #

Server menolak melayani request karena kurangnya izin atau konfigurasi akses.

Penyebab paling umum:

1. Permission file/direktori salah
   → Nginx tidak bisa membaca file karena permission Unix terlalu ketat
   Solusi: cek dan perbaiki permission

2. Direktori tidak punya index file dan autoindex off
   Solusi: tambahkan index.html atau aktifkan autoindex

3. Aturan deny all terkena
   Solusi: cek blok allow/deny di konfigurasi

4. SELinux memblokir akses (CentOS/RHEL)
   Solusi: cek audit log dan set context yang benar

# 1. Cek permission file
ls -la /var/www/html/
# www-data harus bisa membaca file (755 untuk direktori, 644 untuk file)

# 2. Perbaiki permission
sudo chown -R www-data:www-data /var/www/html/
sudo find /var/www/html/ -type d -exec chmod 755 {} \;
sudo find /var/www/html/ -type f -exec chmod 644 {} \;

# 3. SELinux (CentOS/RHEL)
sudo ausearch -c nginx | audit2allow -m nginx
# Atau disable SELinux untuk test (JANGAN di production tanpa solusi permanen):
# sudo setenforce 0

404 Not Found #

File atau resource yang diminta tidak ada atau konfigurasi root/alias salah.

Penyebab paling umum:

1. Path root atau alias salah dikonfigurasi
   → file ada tapi Nginx mencari di tempat yang berbeda

2. Trailing slash yang membingungkan di proxy_pass + location
   → sudah dibahas di artikel proxy-pass

3. SPA routing: user akses /dashboard langsung tapi tidak ada file tersebut
   → butuh try_files $uri $uri/ /index.html

4. File benar-benar tidak ada
   → cek apakah deployment berhasil

# Debug: cek path yang diakses Nginx
# Aktifkan debug log sementara untuk IP tertentu
# Atau tambahkan return untuk melihat apa yang Nginx cari

# Cek apakah file ada di path yang dikira Nginx
ls -la /var/www/html/dashboard   # Ada?
ls -la /var/www/html/dashboard/  # Ada index.html di sini?

413 Request Entity Too Large #

Body request melebihi client_max_body_size.

# Solusi: naikkan batas di server atau location yang relevan
server {
    # Default hanya 1MB — terlalu kecil untuk upload
    client_max_body_size 50m;   # Naikkan sesuai kebutuhan

    # Untuk endpoint upload khusus
    location /upload/ {
        client_max_body_size 500m;
        proxy_pass http://upload_backend;
    }
}

Masalah SSL/TLS Umum #

ERR_SSL_PROTOCOL_ERROR di browser:

# Cek apakah Nginx listen di port 443 dengan ssl
sudo ss -tlnp | grep :443

# Cek apakah ssl_certificate dan ssl_certificate_key ada
sudo ls -la /etc/letsencrypt/live/example.com/

# Validasi konfigurasi
sudo nginx -t

ERR_CERT_AUTHORITY_INVALID (sertifikat tidak dipercaya): Menggunakan ssl_certificate cert.pem (tanpa chain) alih-alih fullchain.pem.

# Salah:
ssl_certificate /etc/letsencrypt/live/example.com/cert.pem;

# Benar:
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;

ERR_CERT_COMMON_NAME_INVALID (domain tidak cocok): Sertifikat untuk domain yang berbeda atau server_name di konfigurasi tidak cocok dengan domain yang diakses.

Sertifikat expired:

# Cek tanggal expiry
sudo certbot certificates
# atau
echo | openssl s_client -connect example.com:443 2>/dev/null | \
    openssl x509 -noout -dates

Nginx Tidak Mau Start / Reload #

# Selalu test konfigurasi sebelum reload
sudo nginx -t

# Lihat error spesifik
sudo nginx -t 2>&1 | head -20

# Masalah umum:
# "bind() to 0.0.0.0:80 failed (98: Address already in use)"
# → ada proses lain yang pakai port 80
sudo ss -tlnp | grep :80

# "PID file /run/nginx.pid not found"
# → Nginx tidak sedang berjalan, gunakan start bukan reload
sudo systemctl start nginx

Ringkasan #

502: backend tidak berjalan atau salah port. Cek systemctl status backend dan akses langsung dengan curl localhost:PORT.
504: backend terlalu lambat. Naikkan proxy_read_timeout untuk endpoint tertentu, investigasi query lambat di backend.
403: permission file salah atau aturan deny. Cek ls -la dan chown/chmod, atau audit log SELinux di CentOS/RHEL.
413: naikkan client_max_body_size di level server atau location upload.
SSL errors: selalu gunakan fullchain.pem (bukan cert.pem) untuk ssl_certificate, dan selalu jalankan nginx -t sebelum reload.

← Sebelumnya: SPA React Berikutnya: Debug Konfigurasi →