Bab 16: Troubleshooting Nginx – Panduan Lengkap

Troubleshooting adalah langkah penting untuk menjaga server tetap stabil dan responsif. Nginx menyediakan mekanisme untuk memeriksa konfigurasi, log, dan mengidentifikasi masalah umum.

---

1. Menguji Konfigurasi (nginx -t)

Sebelum me-reload atau restart Nginx, selalu periksa sintaks konfigurasi:

sudo nginx -t

Output:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

• Syntax error akan ditunjukkan beserta baris konfigurasi bermasalah
• Jika gagal, Nginx tidak akan reload sehingga server tetap berjalan

Tips:

• Jalankan sudo systemctl reload nginx setelah test sukses
• Gunakan nginx -T untuk menampilkan semua konfigurasi aktif

---

2. Log Error Umum

Lokasi default error log:

/var/log/nginx/error.log

Contoh error umum:

1. Port sudah digunakan

bind() to 0.0.0.0:80 failed (98: Address already in use)

• Solusi: cek proses dengan sudo lsof -i :80 atau sudo netstat -tulpn dan hentikan service lain

2. Permission denied

[crit] 1234#0: *1 open() "/var/www/html/index.html" failed (13: Permission denied)

• Solusi: periksa permission folder/file dan user Nginx (www-data di Ubuntu/Debian)

3. FastCGI not running

connect() to unix:/run/php/php8.1-fpm.sock failed

• Solusi: pastikan PHP-FPM berjalan sudo systemctl status php8.1-fpm

---

3. Masalah Port dan Binding

• Pastikan Nginx mendengarkan port yang benar:

sudo lsof -i :80
sudo lsof -i :443

• Jika terjadi konflik dengan Apache atau service lain, hentikan atau ubah port:

sudo systemctl stop apache2

• Gunakan listen 127.0.0.1:8080; untuk testing port berbeda

---

4. Masalah Cache

Proxy Cache

• Cache kadang menampilkan data lama atau error

proxy_cache_path /var/cache/nginx ...

Tips:

• Bersihkan cache manual:

sudo rm -rf /var/cache/nginx/*
sudo systemctl reload nginx

• Gunakan proxy_cache_bypass saat debugging:

proxy_cache_bypass $http_cache_control;

FastCGI Cache

• Pastikan direktori cache memiliki permission benar untuk Nginx
• Gunakan header debug:

add_header X-FastCGI-Cache $upstream_cache_status;

---

5. Tips Debugging Lainnya

1. Aktifkan debug log sementara

error_log /var/log/nginx/error.log debug;

• Menampilkan alur request internal Nginx

2. Periksa file permission dan ownership

ls -l /var/www/html

3. Periksa symlink sites-enabled / sites-available

• Pastikan file konfigurasi aktif dengan:

ls -l /etc/nginx/sites-enabled/

4. Gunakan curl -I untuk cek response header

curl -I http://example.com

• Mengecek status code, redirect, dan headers

5. Restart service dengan aman

sudo systemctl reload nginx   # reload konfigurasi
sudo systemctl restart nginx  # restart total

---

6. Contoh Checklist Troubleshooting Nginx

Masalah	Penyebab Umum	Solusi
502 Bad Gateway	Backend mati / socket error	Pastikan backend berjalan (PHP-FPM / Node.js / Gunicorn)
403 Forbidden	Permission folder/file salah	Set ownership Nginx (www-data)
404 Not Found	File/folder tidak ada atau try_files salah	Periksa root folder dan try_files directive
Port conflict	Port sudah dipakai service lain	Hentikan service lain atau ubah port
Cache tidak update	Proxy/fastcgi cache	Bersihkan cache atau gunakan header bypass
SSL error	Sertifikat tidak ditemukan / expired	Periksa path sertifikat, renew Let’s Encrypt

---

7. Kesimpulan

Troubleshooting Nginx melibatkan:

1. Memeriksa konfigurasi dengan nginx -t
2. Memahami error log dan mencari penyebab umum
3. Memastikan port dan binding tidak konflik
4. Memeriksa cache dan membersihkannya jika diperlukan
5. Menggunakan debug log, curl, dan pemeriksaan permission untuk identifikasi masalah

Dengan metode ini, server tetap stabil, cepat, dan masalah dapat diselesaikan lebih cepat.