Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / DevOps / Mengatasi Error 502 Bad Gatewa...
DevOps

Mengatasi Error 502 Bad Gateway pada Laravel dengan Nginx dan PHP-FPM

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
9 min read
30 views

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_children dan disk di atas 85%.
  • Uji konfigurasi sebelum reload: nginx -t dan php-fpm8.3 -t selalu 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() atau lazy()).
  • 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

  • ☐ nginx dan php8.3-fpm berstatus active.
  • ☐ fastcgi_pass cocok 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 -t dan php-fpm8.3 -t lolos 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.

Bagikan artikel:

Artikel lainnya