Fix 502 Bad Gateway, 503 and 504 errors on your website

502, 503 and 504 errors come from the web server or proxy in front of your application: it is running, but the application behind it (PHP-FPM, Node.js, Python, another backend) did not answer correctly. The logs nearly always name the reason. Commands are for nginx or Apache with PHP-FPM on Ubuntu and Debian; the same approach works for other backends.

Before you start

• Note the exact code and the time, and whether every page fails or only some.
• Log in over SSH. On a hosting account, open the error log in cPanel or Plesk instead.
• Check that the disk is not full (df -h) and memory is available (free -h); both cause these errors. See disk full and high CPU or memory usage.

Step 1: Read the error log

sudo tail -n 50 /var/log/nginx/error.log
sudo tail -n 50 /var/log/apache2/error.log

Reload the failing page and run the command again: the newest lines describe this request. The messages below tell you which section to read.

502 Bad Gateway

The web server could not get a valid response from the backend. Typical nginx messages:

connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory) while connecting to upstream
connect() to unix:/run/php/php8.3-fpm.sock failed (13: Permission denied) while connecting to upstream
upstream prematurely closed connection while reading response header from upstream

Is the backend running? Find and check the PHP-FPM service; its name contains the PHP version:

systemctl list-units 'php*-fpm*'
sudo systemctl status php8.3-fpm
sudo journalctl -u php8.3-fpm -n 50

Replace php8.3-fpm with the name from the first command. If it is stopped, sudo systemctl start it and read why it stopped.

Does the socket path match? The fastcgi_pass line in your nginx site must point to the socket the PHP-FPM pool listens on (listen = in the pool file under /etc/php/). After a PHP upgrade, the version in the path often changes.

Permission denied on the socket means the web server user may not use it. Check listen.owner, listen.group and listen.mode in the pool file.

Premature close means the PHP process crashed or was killed while handling the request: look in the PHP-FPM log and in journalctl -k for out-of-memory kills.

After changes, test and reload:

sudo nginx -t
sudo systemctl reload nginx
sudo systemctl restart php8.3-fpm

503 Service Unavailable

The service refuses work. Common causes:

• All PHP workers are busy. The PHP-FPM log shows server reached pm.max_children setting. Each worker uses memory, so raise pm.max_children only as far as memory allows (roughly: available memory divided by the memory one worker uses), and reduce slow requests with caching.
• Maintenance mode of the application (for example after an interrupted update). Finish or undo the update.
• Rate limits in nginx (limit_req) or a web application firewall reject requests. Check the log for limiting messages.
• A hosting account at its limits. On shared hosting, resource limits (CPU, memory, entry processes) can return 503 errors; check the resource usage in your control panel or move to a larger plan.

504 Gateway Timeout

The backend did not answer within the timeout. nginx logs:

upstream timed out (110: Connection timed out) while reading response header from upstream

Find out what is slow: a database query, an external API call, a large import. The slow query log of your database and the application's own logs help. Only for requests that are slow by design, raise the timeouts in the nginx location, for example:

fastcgi_read_timeout 120s;
proxy_read_timeout 120s;

Use fastcgi_read_timeout for PHP-FPM and proxy_read_timeout for backends behind proxy_pass. PHP's own max_execution_time and request_terminate_timeout in the pool can stop the script earlier; keep them consistent.

Apache

With Apache, look in /var/log/apache2/error.log for proxy errors from mod_proxy or mod_proxy_fcgi, such as failed connections to the backend or timeouts. The causes are the same: the backend is stopped, its socket or port does not match the SetHandler or ProxyPass line, or it is too slow. ProxyTimeout sets the time Apache waits. Test the configuration with sudo apachectl configtest before sudo systemctl reload apache2.

Behind Cloudflare

Errors 520 to 526 come from Cloudflare when your server does not give it a good answer:

Test the server directly, bypassing Cloudflare, with curl -I --resolve example.com:443:203.0.113.10 https://example.com. See Cloudflare in front of your site.

When to open a ticket

If the server itself is unreachable, or the errors start without any change on your side and the logs show nothing, open a ticket with the service selected, the URL, the time with time zone and the relevant log lines. On hosting plans, include the domain and the error log excerpt from the control panel.

Next steps

• Resources running out: high CPU or memory usage.
• Protect the site at the edge: Cloudflare in front of your site.