{"id":1182,"date":"2026-09-19T22:35:27","date_gmt":"2026-09-19T22:35:27","guid":{"rendered":"https:\/\/virtualserversvps.com\/blog\/?p=1182"},"modified":"2026-09-19T22:35:27","modified_gmt":"2026-09-19T22:35:27","slug":"playbook-diagnosing-502-504-gateway-errors-vps","status":"publish","type":"post","link":"https:\/\/virtualserversvps.com\/blog\/playbook-diagnosing-502-504-gateway-errors-vps\/","title":{"rendered":"Troubleshooting Playbook: Diagnosing 502 and 504 Gateway Errors on a VPS"},"content":{"rendered":"\n

A 502 means nginx reached the upstream but got a bad answer, or could not connect at all. A 504 means nginx gave up waiting for an answer. They look similar in a browser and completely different in a log, and the first two minutes of diagnosis determine whether you fix it in five minutes or fifty. This playbook is a decision tree for the common causes on a self-managed VPS running nginx + PHP-FPM + MariaDB.<\/p>\n\n\n\n

Minute 0: Read the Error Log, Not the Access Log<\/h2>\n\n\n\n
tail -50 \/var\/log\/nginx\/error.log\njournalctl -u php8.4-fpm --since '10 min ago' --no-pager | tail -50\ndmesg -T | tail -20   # watch for OOM kills<\/code><\/pre>\n\n\n\n
Error log line<\/th>Meaning<\/th>Jump to<\/th><\/tr><\/thead>
connect() to unix:\/run\/php\/php8.4-fpm.sock failed (2: No such file)<\/code><\/td>Wrong socket path or FPM is down<\/td>Cause A<\/td><\/tr>
connect() ... failed (13: Permission denied)<\/code><\/td>Socket ownership \/ SELinux \/ AppArmor<\/td>Cause B<\/td><\/tr>
recv() failed (104: Connection reset by peer)<\/code><\/td>Worker died mid-request — usually OOM or request_terminate_timeout<\/code><\/td>Cause C<\/td><\/tr>
upstream timed out (110: Connection timed out)<\/code><\/td>504 — upstream slower than fastcgi_read_timeout<\/code><\/td>Cause D<\/td><\/tr>
no live upstreams<\/code><\/td>All pool workers busy or dead<\/td>Cause E<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Match the line you actually see. Guessing which cause applies is how a five-minute fix becomes an afternoon.<\/p>\n\n\n\n
Cause A: Socket Path Mismatch (Most Common After an Upgrade)<\/h2>\n\n\n\n
Ubuntu upgrades from PHP 8.3 to 8.4 create a new socket path while your nginx config still points at the old one. Confirm what exists and what nginx expects, then reconcile them:<\/p>\n\n\n\n
ls -l \/run\/php\/\ngrep -r fastcgi_pass \/etc\/nginx\/\nphp-fpm8.4 -tt 2>&1 | grep -i listen<\/code><\/pre>\n\n\n\n
The durable fix is to pin the pool to a version-independent path so the next upgrade does not repeat the outage:<\/p>\n\n\n\n
# \/etc\/php\/8.4\/fpm\/pool.d\/www.conf\nlisten = \/run\/php\/php-fpm.sock\nlisten.owner = www-data\nlisten.group = www-data\nlisten.mode = 0660<\/code><\/pre>\n\n\n\n
Cause B: Permission Denied on the Socket<\/h2>\n\n\n\n
If nginx runs as www-data<\/code> and FPM’s socket is owned by root:root<\/code> with mode 0660<\/code>, every request fails with the same 502. Check without guessing:<\/p>\n\n\n\n
ps -o user= -C nginx | sort -u\nstat -c '%U %G %a' \/run\/php\/php-fpm.sock\nsudo -u www-data test -w \/run\/php\/php-fpm.sock && echo OK || echo DENIED<\/code><\/pre>\n\n\n\n
The listen.owner<\/code> \/ listen.group<\/code> \/ listen.mode<\/code> directives above fix the common case. On systems with SELinux enforcing, the socket also needs the httpd_sys_rw_content_t<\/code> context — check sudo ausearch -m avc -ts recent<\/code> before blaming permissions.<\/p>\n\n\n\n
Cause C: Workers Dying (OOM or Terminate Timeout)<\/h2>\n\n\n\n
A connection reset almost always means a worker process was killed. Two candidates: the kernel OOM killer, or FPM’s own request_terminate_timeout<\/code>.<\/p>\n\n\n\n
journalctl -k | grep -i 'killed process'\ngrep -i 'execution timed out' \/var\/log\/php8.4-fpm.log\nfree -m<\/code><\/pre>\n\n\n\n
If the OOM killer is involved, the pool is oversubscribed. Cap the FPM pool so that pm.max_children × memory-per-worker<\/code> stays inside available RAM minus the database. On a 2 GB VPS with 45 MB workers and a 700 MB MariaDB buffer pool, that is roughly max_children = 18<\/code>, not the 50 many guides suggest. The full derivation is in tuning PHP-FPM pools by workload type<\/a>.<\/p>\n\n\n\n
Cause D: The 504 That Is Really a Slow Query<\/h2>\n\n\n\n
Raising fastcgi_read_timeout<\/code> from 60 s to 300 s is the wrong fix — it converts a visible error into a hung worker that blocks the whole pool. Find out what the request was waiting for:<\/p>\n\n\n\n
# what was running at the moment of timeout\nmysql -e \"SELECT id, time, state, LEFT(info,80) FROM information_schema.processlist\n          WHERE time > 5 ORDER BY time DESC LIMIT 10;\"\n\n# PHP slow log, if enabled\ntail -100 \/var\/log\/php8.4-fpm-slow.log<\/code><\/pre>\n\n\n\n
A long-running SELECT ... WHERE<\/code> with state = Sending data<\/code> points at a missing index or a buffer pool that no longer covers the working set. A Waiting for table metadata lock<\/code> points at a concurrent ALTER TABLE<\/code>. Neither is fixed in nginx. The classification method in our PHP-FPM slow-log profiling guide<\/a> will tell you which class you are in within one request.<\/p>\n\n\n\n
Cause E: No Live Upstreams (Pool Exhaustion)<\/h2>\n\n\n\n
When every worker is busy, nginx cannot even hand off the request. Confirm the pool is saturated rather than crashed:<\/p>\n\n\n\n
# FPM status page: enable pm.status_path = \/fpm-status first\ncurl -s http:\/\/127.0.0.1\/fpm-status?full | \\\n  grep -E 'active processes|max active|listen queue|max children reached'<\/code><\/pre>\n\n\n\n
listen queue<\/code> above zero means requests are already waiting. max children reached<\/code> confirms the pool ceiling is the binding constraint. If both are true and CPU is not saturated, your bottleneck is downstream (database or network I\/O) and a bigger pool will make it worse, not better.<\/p>\n\n\n\n
The Order of Operations<\/h2>\n\n\n\n