Quick answer
The 502 Bad Gateway error means Nginx cannot get a valid response from the backend service (PHP-FPM, Node.js, Gunicorn). Check whether the backend process is running, whether sockets and ports are available, and whether the logs are full of errors. In most cases, the solution is to restart the backend service or fix the configuration.
How to recognize the problem
- The site shows a white page with the text 502 Bad Gateway
- Some pages work, but dynamic ones (PHP, API) return 502
- The Nginx error log shows connect() failed
- The backend service (PHP-FPM, Node) has crashed or is restarting
- 502 appears intermittently, especially under load
Most common causes
Backend service is not running
PHP-FPM, Node.js, Gunicorn, or another application server has crashed or been stopped. Nginx then has nowhere to forward the request.
Wrong socket or port in the configuration
Nginx points to a non-existent Unix socket or a port where the backend is not listening. The error also occurs after a configuration change or upgrade.
Overloaded backend
If PHP-FPM or the application consumes all resources, they cannot accept new requests. Nginx then returns 502 or 504.
Socket permissions
The Nginx user (e.g. www-data or nginx) does not have permission to access the Unix socket. This often happens after a change of ownership or SELinux policy.
Backend crashes due to a code error
A fatal error in the application can bring down the worker process. The logs show a segfault or PHP Fatal error.
Step-by-step fix
- 1
Check the backend service status
Run
systemctl status php8.2-fpm(or the appropriate service:php-fpm,node,gunicorn). If the service is inactive, trysystemctl restart php8.2-fpm. If it stops again immediately, proceed to reading the logs. - 2
Review the Nginx error log
Open
/var/log/nginx/error.log(or the path fromnginx -T). Look for lines withconnect() failedorno live upstreams. They show whether Nginx cannot connect to the socket or port. - 3
Check whether the backend is listening
For a Unix socket:
ls -l /run/php/php8.2-fpm.sock. For a TCP port:ss -tlnp | grep 3000. If there is no output, the backend is not listening and the problem is in its configuration or startup. - 4
Align the path in the Nginx configuration
In the site file (e.g.
/etc/nginx/sites-enabled/example.conf), checkfastcgi_passorproxy_pass. The socket path or port must match what the backend actually uses. After the change, runnginx -tand thensystemctl reload nginx. - 5
Check socket permissions
The socket should be owned by the user under which the backend runs, and the Nginx user must have access. Adjust permissions if necessary (e.g.
chmod 660and the appropriate group) and restart both services. - 6
Monitor the application logs
Check the PHP error log (
/var/log/php8.2-fpm.log),journalctl -u php8.2-fpm -n 50, or the application log. If you see fatal errors, fix the code or configuration before restarting again. - 7
Test access locally on the server
From the server, run
curl -I -H 'Host: example.com' http://127.0.0.1andcurl -I http://127.0.0.1:3000(if the application listens on that port). If it works locally but not externally, the problem is in the network, firewall, or Nginx configuration. - 8
Restart services in order
First restart the backend (
systemctl restart php8.2-fpm), then Nginx (systemctl restart nginx). Then reload the site. If 502 still persists, go back to the logs.
If nothing helps
If the services are active, sockets available, and logs show no obvious error, check whether the problem is in the network or SELinux. The command getenforce shows whether SELinux is in Enforcing mode; you can temporarily set it to Permissive (setenforce 0) for testing, but be sure to set it back to Enforcing (setenforce 1). Also check whether the disk is full (df -h) and whether there is enough memory (free -m). If 502 occurs only under load, increase the number of PHP-FPM processes or worker_connections in Nginx. For a production environment, consider monitoring that will notify you before users notice the error.
How to prevent it
- Regularly monitor the backend service and set an alarm for downtime
- Keep the Nginx and PHP-FPM configuration aligned with the actual sockets
- Monitor resource usage and increase limits in time
- Test configuration changes with `nginx -t` before reloading
When to call a professional
If the error repeats and requires changes in configuration or code, or if you do not have access to logs and root permissions, it is better to call IT support. They can quickly isolate the cause and prevent a longer site outage.
IT infrastructure maintenance · Servers, networks, backup, security and helpdeskFAQ
Is 502 the same as 504?
No. 502 means the backend returned an invalid response or Nginx could not connect, while 504 means the backend was silent for too long. In practice, they are often resolved similarly, by checking the backend service and logs.
Why does 502 appear only on some pages?
Static files are served directly by Nginx, so they work. Dynamic pages depend on the backend, so they report 502. This confirms that the problem is in the application server, not in Nginx.
Can I restart only PHP-FPM?
Yes, if the problem is in PHP-FPM, `systemctl restart php8.2-fpm` is enough. Restart Nginx only if you changed its configuration or if the problem persists.