Panduan diagnosis sistematis: dari membaca log, mengenali pesan error, sampai menyetel PHP-FPM agar 502 tidak muncul lagi.
Pendahuluan
502 Bad Gateway adalah salah satu error paling membingungkan saat mengelola Laravel di VPS. Halaman putih bertuliskan "502 Bad Gateway nginx" tidak memberi petunjuk apa pun. Padahal artinya sederhana:
Nginx berhasil menerima request, tetapi gagal mendapat jawaban yang valid dari PHP-FPM di belakangnya.
Jadi masalahnya hampir tidak pernah di Laravel itu sendiri, melainkan di jalur antara Nginx dan PHP-FPM, atau di PHP-FPM yang kewalahan atau crash. Artikel ini memberi alur diagnosis yang bisa diikuti berurutan.
Browser ──► Nginx ──(socket / port)──► PHP-FPM ──► Laravel
▲
└── 502 terjadi di sini bila PHP-FPM tidak menjawab
Perbedaan singkat dengan error lain yang mirip:
| Kode | Arti | Biasanya karena |
|---|---|---|
| 502 | Jawaban dari upstream tidak valid atau tidak ada | PHP-FPM mati, socket salah, proses crash |
| 503 | Layanan tidak tersedia | Maintenance mode, server kelebihan beban |
| 504 | Upstream terlalu lama menjawab | Script PHP lambat, timeout |
| 500 | Error di dalam aplikasi | Bug Laravel, izin file, .env |
Langkah 0: Jangan Menebak, Baca Log
Log Nginx adalah sumber petunjuk paling jelas.
sudo tail -n 50 /var/log/nginx/error.log
Buka dua jendela terminal: satu untuk memantau log, satu untuk memicu error dari browser.
sudo tail -f /var/log/nginx/error.log
Pesan di log akan mengarahkan Anda ke salah satu dari penyebab di bawah ini.
Penyebab 1: PHP-FPM Tidak Berjalan
Pesan log:
connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory)
while connecting to upstream
atau
connect() failed (111: Connection refused) while connecting to upstream
Diagnosis:
sudo systemctl status php8.3-fpm --no-pager
○ php8.3-fpm.service - The PHP 8.3 FastCGI Process Manager
Active: inactive (dead)
Solusi:
sudo systemctl start php8.3-fpm
sudo systemctl enable php8.3-fpm # otomatis aktif setelah reboot
Jika gagal start, lihat alasannya:
sudo journalctl -u php8.3-fpm -n 50 --no-pager
sudo php-fpm8.3 -t # uji sintaks konfigurasi
[ERROR] [pool www] cannot get uid for user 'www-datax'
ERROR: FPM initialization failed
Kesalahan ketik di file pool (/etc/php/8.3/fpm/pool.d/www.conf) adalah penyebab umum setelah mengedit konfigurasi.
Penyebab 2: Path Socket Tidak Cocok
Ini sering terjadi setelah upgrade versi PHP. Nginx masih mencari php8.2-fpm.sock, padahal yang aktif php8.3-fpm.
Cek socket yang benar-benar ada:
ls -l /run/php/
srw-rw---- 1 www-data www-data 0 Okt 19 08:12 php8.3-fpm.sock
lrwxrwxrwx 1 root root 30 Okt 19 08:12 php-fpm.sock -> /run/php/php8.3-fpm.sock
Cek yang dipakai Nginx:
grep -R "fastcgi_pass" /etc/nginx/sites-enabled/
/etc/nginx/sites-enabled/laravel-app: fastcgi_pass unix:/run/php/php8.2-fpm.sock;
Solusi: samakan path, uji, lalu muat ulang.
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
sudo nginx -t && sudo systemctl reload nginx
Cara lain yang tidak mudah rusak saat upgrade: arahkan ke symlink umum /run/php/php-fpm.sock (jika tersedia di sistem Anda).
Jika memakai TCP, pastikan nilai listen di pool cocok dengan fastcgi_pass:
; /etc/php/8.3/fpm/pool.d/www.conf
listen = 127.0.0.1:9000
fastcgi_pass 127.0.0.1:9000;
Penyebab 3: Izin Socket (Permission Denied)
Pesan log:
connect() to unix:/run/php/php8.3-fpm.sock failed (13: Permission denied)
Nginx berjalan sebagai user tertentu (biasanya www-data), dan user itu harus boleh mengakses socket.
Diagnosis:
ps aux | grep -E "nginx: worker|php-fpm: pool"
grep -E "^(listen\.(owner|group|mode)|user|group)" /etc/php/8.3/fpm/pool.d/www.conf
grep -E "^user" /etc/nginx/nginx.conf
Solusi: pastikan pemilik dan grup socket sesuai dengan user Nginx.
; /etc/php/8.3/fpm/pool.d/www.conf
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
sudo systemctl restart php8.3-fpm
Penyebab 4: Worker PHP-FPM Habis (max_children)
Ini penyebab 502 yang paling umum di server yang sudah berjalan lama dan mulai ramai. Gejalanya khas: situs normal, lalu saat traffic naik muncul 502 atau lambat, dan kembali normal setelah beberapa saat.
Pesan log PHP-FPM:
sudo tail -n 30 /var/log/php8.3-fpm.log
WARNING: [pool www] server reached pm.max_children setting (5), consider raising it
Artinya semua worker sibuk, dan request baru tidak mendapat giliran.
Menghitung pm.max_children dengan benar
Jangan asal besar. Terlalu besar akan menghabiskan RAM, memicu OOM killer, dan malah menimbulkan 502 yang lebih parah.
1. Ukur memori rata-rata satu proses PHP-FPM:
ps --no-headers -o rss -C php-fpm8.3 | awk '{sum+=$1; n++} END {printf "Rata-rata: %.1f MB (dari %d proses)\n", sum/n/1024, n}'
Rata-rata: 48.3 MB (dari 6 proses)
2. Hitung:
max_children = (RAM yang dialokasikan untuk PHP) / (rata-rata memori per proses)
Contoh: server 4 GB RAM. Sisakan sekitar 1,5 GB untuk sistem, MySQL, Redis, dan Nginx. Sisanya 2,5 GB untuk PHP-FPM.
2500 MB / 50 MB = 50 proses
3. Terapkan:
; /etc/php/8.3/fpm/pool.d/www.conf
pm = dynamic
pm.max_children = 40
pm.start_servers = 8
pm.min_spare_servers = 5
pm.max_spare_servers = 15
pm.max_requests = 500
pm.max_requests me-restart worker setelah sejumlah request, sebagai pengaman bila ada kebocoran memori.
sudo php-fpm8.3 -t && sudo systemctl reload php8.3-fpm
Pantau memori setelah perubahan:
free -h
total used free shared buff/cache available
Mem: 3.8Gi 2.9Gi 112Mi 42Mi 0.9Gi 0.7Gi
Jika available mendekati nol saat ramai, kurangi max_children, jangan menaikkannya.
Penyebab 5: PHP-FPM Crash atau Request Terputus
Pesan log Nginx:
upstream prematurely closed connection while reading response header from upstream
recv() failed (104: Connection reset by peer) while reading response header from upstream
Proses PHP berhenti di tengah jalan. Cek log PHP-FPM dan sistem:
sudo tail -n 50 /var/log/php8.3-fpm.log
sudo dmesg -T | grep -i -E "killed process|out of memory|segfault"
[Sun Okt 19 09:41:07 2026] Out of memory: Killed process 18422 (php-fpm8.3) total-vm:612340kB
Penyebab dan solusi:
| Temuan | Penyebab | Solusi |
|---|---|---|
Out of memory: Killed process |
RAM habis | Kurangi max_children, tambah RAM atau swap, optimasi script |
child exited on signal 11 (SIGSEGV) |
Crash ekstensi PHP | Nonaktifkan ekstensi yang baru dipasang, update PHP |
Allowed memory size exhausted |
memory_limit tercapai |
Perbaiki query/loop boros memori, bukan sekadar naikkan limit |
Maximum execution time exceeded |
Script terlalu lama | Pindahkan ke queue (lihat artikel Laravel Queue) |
Untuk memeriksa ekstensi yang aktif dan mencari yang bermasalah:
php -m
sudo phpdismod nama_ekstensi
sudo systemctl restart php8.3-fpm
Penyebab 6: Header atau Response Terlalu Besar
Pesan log:
upstream sent too big header while reading response header from upstream
Biasanya karena cookie atau header yang sangat besar (misalnya session berisi banyak data atau banyak header debug).
# di blok location ~ \.php$
fastcgi_buffer_size 32k;
fastcgi_buffers 16 16k;
fastcgi_busy_buffers_size 32k;
Tetapi akar masalahnya sebaiknya dicari: jangan menyimpan data besar di session atau cookie.
Penyebab 7: Script Lambat (502 atau 504)
Bila script berjalan lebih lama dari batas Nginx atau PHP-FPM, hasilnya bisa 504 atau 502.
; php.ini / pool
max_execution_time = 60
request_terminate_timeout = 60s ; di pool.d/www.conf
fastcgi_read_timeout 60s;
Menaikkan timeout hanya menyembunyikan masalah. Cari script lambatnya dengan slow log PHP-FPM:
; pool.d/www.conf
slowlog = /var/log/php8.3-fpm-slow.log
request_slowlog_timeout = 5s
sudo systemctl reload php8.3-fpm
sudo tail -f /var/log/php8.3-fpm-slow.log
[pool www] pid 21877
script_filename = /var/www/laravel-app/public/index.php
[0x00007f...] curl_exec() /var/www/laravel-app/vendor/guzzlehttp/guzzle/...
[0x00007f...] App\Services\ReportService->export() /var/www/laravel-app/app/Services/ReportService.php:88
Dari sini terlihat fungsi mana yang menahan worker. Untuk pekerjaan berat seperti ekspor laporan, panggilan API eksternal, dan kirim email massal, pindahkan ke queue agar tidak memblokir worker web.
Penyebab 8: Setelah Deploy atau Perubahan Konfigurasi
Kadang 502 muncul tepat setelah deploy. Periksa:
# konfigurasi Nginx valid?
sudo nginx -t
# konfigurasi PHP-FPM valid?
sudo php-fpm8.3 -t
# layanan berjalan?
systemctl is-active nginx php8.3-fpm mysql
# disk penuh? (sering terlupa)
df -h
Filesystem Size Used Avail Use% Mounted on
/dev/vda1 50G 50G 0 100% /
Disk penuh (sering oleh storage/logs) membuat PHP-FPM gagal menulis sehingga request gagal. Bersihkan log lama dan atur rotasi:
sudo du -sh /var/www/laravel-app/storage/logs
sudo truncate -s 0 /var/www/laravel-app/storage/logs/laravel.log
Di Laravel, gunakan log harian dengan batas hari:
LOG_CHANNEL=daily
LOG_DAILY_DAYS=14
Alur Diagnosis Cepat
Urutkan pemeriksaan dari yang termurah:
# 1. Apakah layanan hidup?
systemctl is-active nginx php8.3-fpm
# 2. Apa kata log Nginx?
sudo tail -n 30 /var/log/nginx/error.log
# 3. Apa kata log PHP-FPM?
sudo tail -n 30 /var/log/php8.3-fpm.log
# 4. Apakah socket-nya ada, dan bisa diakses?
ls -l /run/php/
# 5. Apakah memori atau disk habis?
free -h && df -h
# 6. Apakah ada proses yang dibunuh sistem?
sudo dmesg -T | grep -i -E "killed process|out of memory"
| Pesan di Log | Kemungkinan Penyebab | Bagian |
|---|---|---|
No such file or directory pada socket |
FPM mati / path salah | 1 dan 2 |
Connection refused |
FPM tidak listen di port itu | 1 dan 2 |
Permission denied |
Izin socket | 3 |
reached pm.max_children |
Worker habis | 4 |
upstream prematurely closed |
Crash atau OOM | 5 |
upstream sent too big header |
Header besar | 6 |
upstream timed out |
Script lambat | 7 |
Pencegahan
- Pantau penggunaan CPU, memori, dan disk (misalnya Netdata atau Uptime Kuma untuk uptime).
- Atur alert untuk
reached pm.max_childrendan disk di atas 85%. - Uji konfigurasi sebelum reload:
nginx -tdanphp-fpm8.3 -tselalu dijalankan di skrip deploy. - Pindahkan tugas berat ke queue, jangan dijalankan di request web.
- Aktifkan OPcache dan hindari memuat data berlebihan ke memori (gunakan
chunk()ataulazy()). - Catat versi PHP di dokumentasi server, agar upgrade tidak membuat path socket usang.
- Lakukan uji beban setelah mengubah tuning untuk melihat batas sebenarnya.
Checklist Troubleshooting 502
- ☐
nginxdanphp8.3-fpmberstatus active. - ☐
fastcgi_passcocok dengan socket atau port yang dipakai PHP-FPM. - ☐ User Nginx boleh mengakses socket (
listen.owner,listen.group,listen.mode). - ☐ Log PHP-FPM tidak menampilkan
reached pm.max_children. - ☐ RAM dan disk masih tersedia, dan tidak ada proses terbunuh OOM.
- ☐ Tidak ada ekstensi PHP yang menyebabkan segfault.
- ☐ Script lambat sudah dicari lewat slow log dan dipindahkan ke queue bila perlu.
- ☐
nginx -tdanphp-fpm8.3 -tlolos sebelum setiap reload.
Penutup
Error 502 hampir selalu bisa dilacak dalam beberapa menit bila Anda mengikuti urutan yang benar: layanan hidup, path dan izin socket, log, lalu sumber daya. Kunci pencegahannya adalah tuning PHP-FPM yang dihitung dari memori nyata, bukan tebakan, serta memindahkan pekerjaan berat keluar dari siklus request. Dengan itu, 502 berubah dari masalah misterius menjadi sinyal yang jelas untuk ditindaklanjuti.