A 502 Bad Gateway on an Nginx VPS means Nginx accepted the request, then failed to get a valid response from the upstream service it was proxying to. That upstream is often PHP-FPM, a Node or Python process, or another container behind proxy_pass. The browser error is only a symptom. The useful details are in the Nginx error log, the upstream service state and the socket or port those two sides are supposed to share.
This guide is for a Linux VPS where you control Nginx. It is not a plugin-by-plugin WordPress repair manual, and it does not rank hosts. Work through the checks in order so you do not restart the wrong service or open a firewall port that was never the problem.
502 vs 504 vs 503
| Status | What it usually means | First place to look |
|---|---|---|
| 502 Bad Gateway | Nginx could not get a usable response from the upstream | Upstream down, wrong socket or port, crashed worker, connection reset |
| 504 Gateway Timeout | Nginx waited for the upstream and gave up | Slow application, locked database, short proxy or FastCGI timeouts |
| 503 Service Unavailable | The server or application is deliberately refusing work, or is overloaded | Maintenance page, exhausted PHP workers, temporary app shutdown |
| 500 Internal Server Error | The application itself failed after Nginx reached it | Application logs, PHP errors, framework exceptions |
People often treat 502 and 504 as the same “site is down” message. A timeout points at a slow or stuck upstream. A 502 often means Nginx never got a proper HTTP or FastCGI response at all, including when the socket is missing or the process has exited.
Step 1: read the Nginx error log first
On Ubuntu or Debian, the site log is often /var/log/nginx/error.log, or a per-site file you set in the server block. Look at the same timestamp as the failed request:
sudo tail -n 80 /var/log/nginx/error.log
sudo nginx -t
sudo systemctl status nginx --no-pager
Typical 502 lines mention connect() failed (111: Connection refused), No such file or directory on a .sock path, Connection reset by peer, or an upstream prematurely closed the connection. Those phrases tell you whether to chase a missing socket, a closed port, a crash, or a protocol mismatch.
nginx -t must succeed before you reload anything. A broken server block can leave you with a different error after a restart, which only muddies the first 502.
Step 2: confirm what Nginx is proxying to
Open the server block or the snippet it includes and find the upstream target:
grep -R "fastcgi_pass\|proxy_pass\|upstream " /etc/nginx/sites-enabled /etc/nginx/conf.d
PHP sites usually pass to a Unix socket such as unix:/run/php/php8.3-fpm.sock or to 127.0.0.1:9000. Application proxies use proxy_pass http://127.0.0.1:3000 or a named upstream block. Write down the exact socket path or port. A version bump from PHP 8.3 to 8.4 is a classic way to leave Nginx pointing at a socket that no longer exists.
The Linux VPS website guide and the PHP VPS guide are useful if you need to rebuild a clean server block after you find a path typo. Do not copy a socket path from a tutorial if ls on your VPS shows a different filename.
Step 3: check the upstream service and the socket
For PHP-FPM on Ubuntu or Debian:
systemctl list-units 'php*-fpm*' --no-pager
sudo systemctl status php8.3-fpm --no-pager
ls -l /run/php/
sudo ss -ltnp | grep -E 'php|9000|3000'
Adjust the unit name to the version you actually run. If the service is failed or inactive, start it and read its journal:
sudo systemctl enable --now php8.3-fpm
sudo journalctl -u php8.3-fpm -e --no-pager
If the service is running but the socket path in Nginx does not match ls /run/php/, fix the fastcgi_pass line, test the config, and reload Nginx. If the socket exists and still cannot be opened, check permissions and the user Nginx runs as, usually www-data on Debian-family images. On Ubuntu, AppArmor can also deny access to an unexpected socket path after you change it by hand. If the error log mentions permission denied rather than a missing file, check the socket owner, the pool listen.owner and listen.group settings, and any AppArmor denial in sudo journalctl -t apparmor --since today. Fix the path and the access policy instead of running PHP as root.
For a Node, Python or other HTTP upstream:
sudo systemctl status myapp --no-pager
sudo ss -ltnp | grep 3000
curl -sI http://127.0.0.1:3000/
If curl from the VPS itself fails, Nginx cannot succeed either. Fix the application process first: missing environment variables, a failed database connection, or a bind address that is not localhost when you think it is. Container setups add one more layer. A published port in Docker is not always the port Nginx is using, and a stopped container produces exactly this 502.
Step 4: look for crashes, memory pressure and file limits
A process that dies under load will come up as 502, often with Connection reset by peer or a flood of PHP-FPM child exits. Check memory, disk and recent kernel messages:
free -h
df -h
sudo dmesg -T | tail -n 50
sudo journalctl -p err --since "1 hour ago" --no-pager
An out-of-memory kill is easy to miss if you only restart Nginx. So is a full disk that prevents PHP-FPM from writing a socket or a session file. The Linux monitoring guide helps you separate CPU, memory and disk before you raise PHP pm.max_children at random.
If PHP-FPM is up but every worker is busy, you may see 502 or 503 depending on timing. Check the pool config, usually under /etc/php/8.3/fpm/pool.d/www.conf, and compare pm.max_children with memory use. Raising the limit on a 1 GB VPS can make the box worse. Size the workers against RAM, then watch the pool status if you have it enabled.
Step 5: review timeouts and header sizes, without hiding a hang
Timeouts more often produce 504, but a short-lived upstream that dies mid-response can still surface as 502. If the error log shows timeouts, inspect the relevant directives rather than raising every number you find:
grep -R "fastcgi_read_timeout\|proxy_read_timeout\|fastcgi_buffers\|proxy_buffers" /etc/nginx/sites-enabled /etc/nginx/nginx.conf
A slow database query or a locked WordPress plugin should be fixed in the application or the database, not masked with a five-minute timeout. Use a longer timeout only when you have a known long-running endpoint and you are watching it. The official behavior of these directives is described in the Nginx proxy module documentation and the FastCGI module documentation.
Step 6: reload carefully and confirm from outside
After a config or socket fix:
sudo nginx -t && sudo systemctl reload nginx
curl -sI https://example.com/
# or, while DNS is still pointing elsewhere:
curl -sI --resolve example.com:443:127.0.0.1 https://example.com/
Test the same URL that failed, not only the homepage. A 502 limited to /wp-admin or an API path can be a different upstream, a longer request, or a permission problem that the front page does not hit. Keep a copy of the last working server block. If you changed PHP-FPM and Nginx, note both so you can reverse one change at a time.
If the VPS itself is healthy and Nginx can reach the upstream locally, but the public site still fails, look at a proxy or CDN in front of the VPS, not at PHP-FPM. The origin error and the edge error are not always the same status code.
A short worked example
Suppose the homepage started returning 502 after a routine apt upgrade. The error log shows connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory). ls /run/php/ now lists php8.4-fpm.sock, and systemctl status php8.4-fpm is active. Nginx is still talking to a path the upgrade left behind.
The fix is to point fastcgi_pass at the new socket, or to install and enable the PHP 8.3 FPM package if the application is not ready for 8.4. Then run sudo nginx -t, reload Nginx, and request the same URL again. If the log changes to Connection reset by peer, the socket path is no longer the issue and you should read the PHP-FPM log for a crash during that request.
Keep a copy of the last working site config before you edit it. The VPS backup and restore guide is the right place to put that habit, especially before package upgrades that change socket names or default PHP versions.
What not to do
Do not set fastcgi_pass to a public interface. Do not open TCP 9000 or your app port on the firewall as a “fix” for a local socket typo. Those ports belong on localhost unless you have a deliberate, protected private network. For a new server, return to the VPS setup checklist after the site answers again, and keep backups so a bad package upgrade is reversible.
Rebooting the whole VPS can hide a full disk or a failed unit for one boot and then surprise you later. Collect the error log line, the unit status and the socket path first.
Frequently asked questions
Can a plugin or theme cause a 502?
Yes, if they crash PHP-FPM or the application process. You will still see an Nginx 502 because Nginx is the public front end. The cause is in the application or PHP log, not in an Nginx typo. Disable the last change from a working backup or a staging copy rather than editing Nginx first.
Why did this start right after a PHP upgrade?
The new PHP-FPM package often uses a new socket name. Nginx is still pointing at the old one. Update fastcgi_pass, or reinstall the expected FPM version, then test and reload.
Does restarting Nginx fix a 502?
Only if Nginx itself is in a bad state. When the upstream is down, reloading Nginx changes nothing useful. Start or repair the upstream, then confirm with curl to the socket or localhost port.
I get 502 only under load. What should I check?
Look at memory, PHP-FPM worker limits, database slow queries and upstream crashes. Add a little observability before you raise every timeout. A worker limit that is too high can OOM the VPS and make the 502 worse.
Is 502 a sign that the VPS was hacked?
Usually no. Treat it as a process, path or resource problem first. Unexpected processes or modified binaries are a separate investigation once the site is stable or once you have a rescue environment.