Server Solusi – Website yang tiba-tiba menampilkan pesan 504 Gateway Timeout biasanya mengalami masalah ketika sebuah server menunggu respons dari server lain terlalu lama. Pada konfigurasi yang menggunakan Nginx sebagai reverse proxy, kondisi ini sering berkaitan dengan backend yang lambat merespons atau tidak mengirimkan data dalam batas waktu yang ditentukan.

Masalahnya, penyebab keterlambatan tidak selalu berada di Nginx. Aplikasi PHP, query database, API eksternal, atau keterbatasan resource VPS juga bisa membuat permintaan membutuhkan waktu lebih lama dari biasanya.

Cara mengatasi error 504 Gateway Timeout Nginx adalah memeriksa error log, menguji respons backend, dan mencari penyebab keterlambatan sebelum mengubah pengaturan timeout. Jika sumber masalahnya sudah diketahui, kamu bisa menentukan apakah perlu memperbaiki aplikasi, menyesuaikan konfigurasi proxy, atau menangani keterbatasan resource server.

Apa Penyebab Error 504 Gateway Timeout Nginx?

Error 504 terjadi ketika gateway atau proxy tidak memperoleh respons tepat waktu dari server upstream sesuai mekanisme timeout yang berlaku. Dalam konfigurasi Nginx, upstream merupakan server atau aplikasi tujuan yang menerima permintaan dari Nginx.

Beberapa penyebab yang perlu diperiksa adalah:

• Backend memproses permintaan terlalu lama. Aplikasi membutuhkan waktu lebih panjang untuk menjalankan proses tertentu.

• PHP-FPM kehabisan worker. Semua worker yang tersedia sedang sibuk sehingga permintaan baru harus menunggu.

• Query database lambat. Query yang berat atau terkunci bisa memperpanjang waktu respons aplikasi.

• API eksternal tidak merespons. Aplikasi menunggu layanan pihak ketiga yang mengalami gangguan atau keterlambatan.

• Resource VPS terbatas. CPU, RAM, atau kapasitas proses tidak cukup untuk menangani beban yang sedang terjadi.

• Timeout proxy terlalu singkat. Batas waktu yang digunakan tidak sesuai dengan kebutuhan proses aplikasi.

• Masalah jaringan antarlayanan. Koneksi dari Nginx menuju backend atau layanan lain mengalami keterlambatan.

Penyebab tersebut masih berupa kemungkinan sampai ada bukti dari log dan pengujian. Jangan langsung menaikkan timeout karena tindakan itu belum tentu menyelesaikan masalah yang sebenarnya.

1. Periksa Error Log Nginx

Langkah pertama yang saya sarankan adalah melihat pesan error yang muncul ketika website mengalami timeout. Log dapat menunjukkan apakah Nginx menunggu respons dari upstream, gagal membangun koneksi, atau mengalami masalah lain.

Pada Ubuntu dan Debian dengan instalasi Nginx standar, error log biasanya berada di /var/log/nginx/error.log. Lokasi ini bisa berbeda jika kamu menggunakan Docker, panel hosting, atau konfigurasi khusus.

Jalankan perintah berikut:

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

Perintah ini menampilkan 100 baris terakhir dari error log.

Jika kamu ingin melihat pesan baru secara langsung, gunakan:

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

Biarkan terminal terbuka, lalu akses kembali halaman yang bermasalah. Tekan Ctrl+C setelah selesai memantau.

Perhatikan pesan yang mengandung kata-kata berikut:

Contoh pesan upstream timed out merupakan petunjuk bahwa komunikasi dengan upstream mengalami timeout. Namun, bagian pesan setelahnya dan kondisi aplikasi tetap perlu diperiksa untuk mengetahui penyebabnya.

2. Periksa Status Nginx dan Backend

Nginx mungkin masih berjalan ketika error 504 muncul. Karena itu, kamu perlu memeriksa Nginx dan aplikasi yang berada di belakangnya secara terpisah.

Periksa status Nginx

sudo systemctl status nginx

Jika status menunjukkan active (running), proses Nginx sedang berjalan. Akan tetapi, status ini belum memastikan bahwa backend merespons dengan baik.

Periksa PHP-FPM jika website menggunakan PHP

Cari nama service PHP-FPM yang tersedia:

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

Setelah menemukan nama yang sesuai, periksa statusnya. Misalnya, jika service yang digunakan adalah php8.3-fpm:

sudo systemctl status php8.3-fpm

Sesuaikan nama service dengan versi PHP yang benar-benar terpasang.

Untuk memeriksa log PHP-FPM melalui systemd:

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

Perintah ini membantu menemukan pesan tentang worker yang sibuk, kegagalan proses, atau masalah startup jika tersedia di journal.

Jika backend menggunakan Node.js, Apache, atau layanan lain, periksa service yang benar-benar digunakan oleh aplikasi tersebut.

Jika service aktif tetapi website tetap timeout, lanjutkan pemeriksaan pada proses aplikasi dan durasi pemrosesannya. Status aktif tidak menjamin aplikasi mampu menyelesaikan setiap permintaan dengan cepat.

3. Periksa Apakah Backend Benar-Benar Lambat

Untuk konfigurasi reverse proxy, kamu bisa menguji backend secara langsung dari server.

Misalnya, Nginx meneruskan permintaan ke aplikasi pada port 3000. Uji dengan:

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

Ganti alamat, port, dan path sesuai konfigurasi backend kamu.

Perintah tersebut mencoba mengakses backend dengan batas waktu 15 detik.

Cara membaca hasilnya:

• Respons HTTP diterima dengan cepat: Backend dapat merespons endpoint yang diuji. Periksa apakah endpoint website yang bermasalah menggunakan proses berbeda.

• Respons muncul setelah waktu lama: Periksa proses aplikasi, database, dan layanan eksternal yang digunakan.

• Terjadi timeout: Cari tahu apakah backend sedang sibuk, menunggu operasi lain, atau mengalami masalah koneksi.

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

• HTTP 500: Backend memberikan respons kesalahan aplikasi. Periksa log aplikasi untuk mencari penyebabnya.

Pengujian ini hanya mengukur endpoint yang kamu panggil. Hasilnya belum tentu menggambarkan kondisi semua halaman website.

Ukur durasi respons website

Kamu juga bisa memeriksa berapa lama permintaan ke website selesai diproses:

curl -sS -o /dev/null \-w 'HTTP: %{http_code}\nTotal time: %{time_total}s\n' \--max-time 30 https://example.com/

Ganti example.com dengan domain kamu.

Nilai time_total menunjukkan waktu total permintaan yang diuji hingga selesai atau gagal. Jika permintaan berakhir dengan timeout, periksa juga kode keluar curl dan error log agar hasilnya tidak disalahartikan sebagai respons HTTP biasa.

4. Periksa Konfigurasi proxy_read_timeout

Jika log menunjukkan timeout ketika Nginx membaca respons dari backend, periksa nilai proxy_read_timeout yang berlaku.

Dokumentasi Nginx menyatakan bahwa proxy_read_timeout menentukan batas jeda antara dua operasi pembacaan berturut-turut dari server upstream. Ini bukan batas total durasi seluruh permintaan. Jika upstream tidak mengirimkan data dalam periode tersebut, koneksi akan ditutup.

Contoh konfigurasi:

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

Angka pada contoh tersebut bukan rekomendasi universal. Gunakan konfigurasi sesuai kebutuhan aplikasi dan hasil diagnosis.

Perhatikan fungsi masing-masing pengaturan:

• proxy_connect_timeout: batas waktu untuk membangun koneksi ke backend.

• proxy_send_timeout: batas jeda saat Nginx mengirimkan permintaan ke backend.

• proxy_read_timeout: batas jeda saat Nginx menunggu data dari backend.

Jika proses aplikasi memang membutuhkan waktu lebih lama, kamu dapat mempertimbangkan penyesuaian timeout yang sesuai. Namun, apabila backend berhenti bekerja atau menunggu query yang macet, menaikkan timeout hanya membuat pengunjung menunggu lebih lama.

Terapkan perubahan dengan aman

Sebelum mengubah konfigurasi, simpan salinan file yang akan diedit. Setelah perubahan dilakukan, uji sintaks konfigurasi:

sudo nginx -t

Jika pengujian berhasil, muat ulang konfigurasi:

sudo systemctl reload nginx

Setelah itu, uji kembali endpoint yang bermasalah dan amati error log.

Jangan melakukan perubahan di sembarang blok location. Pastikan kamu mengedit virtual host yang benar dan memahami apakah ada konfigurasi timeout lain pada tingkat http, server, atau location.

5. Jika Menggunakan PHP-FPM, Periksa Worker yang Sibuk

Pada website berbasis PHP, timeout dapat terjadi ketika aplikasi memerlukan waktu lama untuk menyelesaikan proses atau semua worker PHP-FPM sedang menangani permintaan lain.

Periksa log PHP-FPM dan konfigurasi pool yang digunakan. Jika status PHP-FPM tersedia pada instalasi kamu, informasi tersebut dapat membantu melihat apakah worker sedang sibuk.

Beberapa hal yang perlu diperiksa:

1. Apakah ada request yang berjalan lama?

2. Apakah aplikasi menunggu database atau API eksternal?

3. Apakah jumlah worker terlalu sedikit untuk beban yang diterima?

4. Apakah RAM mencukupi jika jumlah worker ditingkatkan?

5. Apakah ada pesan peringatan tentang max_children atau worker yang mencapai batas?

Nama parameter dan ketersediaan status bergantung pada konfigurasi PHP-FPM yang digunakan.

Jangan langsung menaikkan pm.max_children tanpa menghitung kebutuhan memori. Jumlah worker yang lebih besar bisa meningkatkan penggunaan RAM dan justru menyebabkan server kehabisan memori.

Jika log menunjukkan proses PHP yang lambat, cari endpoint dan operasi aplikasi yang membutuhkan waktu paling lama. Memperbaiki query atau proses tersebut sering lebih tepat daripada hanya memperbesar kapasitas worker.

6. Periksa Database dan API Eksternal

Tidak semua timeout berasal dari koneksi antara Nginx dan backend. Aplikasi mungkin berhasil menerima permintaan tetapi membutuhkan waktu lama untuk mengambil data dari database atau menunggu API lain.

Jika kamu menggunakan MySQL atau MariaDB, periksa log database dan aktivitas query sesuai konfigurasi server. Cari indikasi query lambat, lock yang berkepanjangan, atau koneksi database yang habis.

Untuk aplikasi yang menggunakan API eksternal, periksa:

• Apakah layanan tujuan dapat diakses?

• Apakah ada timeout pada HTTP client aplikasi?

• Apakah permintaan eksternal mengalami keterlambatan?

• Apakah aplikasi mencoba mengulang permintaan terlalu banyak?

• Apakah kegagalan hanya terjadi pada endpoint yang memakai layanan tersebut?

Contohnya, halaman yang menampilkan data dari API pihak ketiga bisa mengalami timeout meskipun Nginx dan PHP-FPM berjalan normal.

Solusi harus disesuaikan dengan sumber keterlambatan. Kamu mungkin perlu mengoptimalkan query, menambahkan caching yang sesuai, mengatur timeout pada HTTP client, atau menghindari permintaan eksternal yang tidak perlu pada setiap kunjungan.

7. Periksa Penggunaan Resource VPS

Jika timeout muncul ketika trafik meningkat, periksa apakah server memiliki cukup resource untuk memproses permintaan.

Periksa memori

free -h

Perintah ini menampilkan penggunaan RAM dan swap. Perhatikan kondisi memori ketika error terjadi, bukan hanya setelah beban kembali normal.

Periksa load average

uptime

Load average perlu dibandingkan dengan jumlah CPU dan jenis beban server. Nilai tinggi bisa menjadi petunjuk, tetapi tidak cukup untuk memastikan penyebab timeout.

Periksa kapasitas disk

df -h

Partisi yang hampir penuh dapat mengganggu aplikasi dan layanan pendukung, misalnya ketika sistem tidak dapat menulis file atau log dengan normal.

Jika resource terlihat terbatas, periksa proses yang paling banyak menggunakan CPU atau RAM. Kamu bisa menggunakan top untuk melihat aktivitas proses secara langsung.

Hindari langsung menambah kapasitas VPS sebelum memahami pola penggunaan resource. Optimasi aplikasi, pengaturan worker, dan pemeriksaan query database mungkin lebih relevan dalam beberapa kasus.

8. Verifikasi Apakah Error 504 Sudah Hilang

Setelah melakukan perubahan, uji website dari sisi server dan browser.

Jalankan:

curl -sS -o /dev/null \-w 'HTTP: %{http_code}\nTotal time: %{time_total}s\n' \--max-time 30 https://example.com/

Kemudian periksa error log:

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

Jika website kembali merespons, pastikan endpoint yang sebelumnya bermasalah juga sudah diuji. Halaman utama yang berhasil dibuka belum tentu membuktikan bahwa proses login, pencarian, atau API berfungsi normal.

Jika pesan upstream timed out masih muncul, bandingkan waktu kejadian dengan log aplikasi dan database. Gunakan informasi tersebut untuk menentukan apakah keterlambatan berasal dari backend, layanan pendukung, atau konfigurasi timeout.

9. Cara Mencegah Error 504 Terulang

Beberapa langkah yang dapat membantu mengurangi risiko timeout berulang:

• Pantau error log Nginx dan log aplikasi secara berkala.

• Catat durasi respons endpoint yang penting.

• Optimalkan query database dan proses aplikasi yang lambat.

• Gunakan caching jika sesuai dengan kebutuhan data.

• Pantau penggunaan RAM, CPU, dan worker backend.

• Sesuaikan timeout berdasarkan hasil pengukuran.

• Simpan backup konfigurasi sebelum mengubah server produksi.

• Jalankan nginx -t sebelum reload konfigurasi.

• Periksa ketergantungan pada API eksternal dan mekanisme retry aplikasi.

Pemantauan yang baik membantu kamu mengetahui apakah timeout merupakan kejadian sesekali atau gejala masalah kapasitas dan performa yang lebih luas.

FAQ Seputar Error 504 Gateway Timeout Nginx

1. Apa perbedaan error 502 dan 504 pada Nginx?

Error 502 berkaitan dengan respons upstream yang tidak valid atau kegagalan komunikasi tertentu dengan backend. Error 504 menunjukkan bahwa gateway atau proxy tidak memperoleh respons tepat waktu. Untuk memastikan penyebab spesifik, periksa pesan pada error log.

2. Apakah menaikkan proxy_read_timeout bisa mengatasi error 504?

Bisa jika permintaan membutuhkan waktu lebih lama daripada batas timeout yang berlaku dan backend tetap mampu menyelesaikannya. Namun, jika aplikasi macet, database lambat, atau backend tidak mengirimkan data, menaikkan timeout saja belum tentu menyelesaikan masalah.

3. Kenapa error 504 muncul hanya pada halaman tertentu?

Halaman tersebut mungkin menjalankan query berat, memanggil API eksternal, atau melakukan proses yang berbeda dari halaman lain. Bandingkan endpoint yang bermasalah dengan endpoint yang normal, kemudian periksa log dan durasi respons masing-masing.

4. Apakah error 504 selalu disebabkan oleh VPS yang lambat?

Tidak. Resource VPS merupakan salah satu kemungkinan, tetapi timeout juga bisa berasal dari aplikasi, database, API eksternal, jaringan, atau konfigurasi proxy. Gunakan hasil diagnosis untuk menentukan sumber masalah.

5. Apakah restart Nginx bisa memperbaiki error 504?

Restart bukan solusi utama untuk semua kasus. Jika backend lambat, database bermasalah, atau proses aplikasi kehabisan resource, masalah dapat kembali muncul. Periksa penyebab timeout terlebih dahulu dan lakukan tindakan yang sesuai dengan temuan.

Kesimpulan

Cara mengatasi error 504 Gateway Timeout Nginx yang efektif dimulai dengan membaca error log, memeriksa backend, mengukur waktu respons, dan mengidentifikasi proses yang menyebabkan keterlambatan.

Jika masalah berkaitan dengan proxy_read_timeout, sesuaikan pengaturannya berdasarkan kebutuhan aplikasi. Jika sumbernya adalah PHP-FPM, database, API eksternal, atau resource VPS, perbaiki bagian tersebut agar timeout tidak sekadar tertunda.

Apabila error masih terjadi, gunakan waktu kejadian dan pesan log yang spesifik untuk menelusuri proses yang lambat. Diagnosis berbasis bukti akan membantu kamu menentukan solusi tanpa melakukan perubahan konfigurasi yang tidak diperlukan.