502 Bad Gateway

What this error means & how to recognize it

• The browser shows 502 Bad Gateway or Bad Gateway, sometimes with Nginx, Apache, Cloudflare, or another proxy’s branding.
• The error affects multiple users, begins after a deployment or configuration change, or appears during a traffic increase.
• Failures may be intermittent when backend workers, memory, CPU, or database connections are exhausted.
• The proxy log reports a failed upstream connection, timeout, unreadable status line, malformed response, oversized headers, or socket error.
• A direct origin request works while the same request through a CDN returns 502, pointing toward CDN-to-origin access, firewall, TLS, or routing problems.

Root causes, ordered by likelihood

1. Stopped or crashing backend: PHP-FPM, Node.js, Gunicorn, or another application process has stopped, is crash-looping, or failed to start after deployment.
2. Backend overload or timeout: Workers, memory, CPU, database connections, or another dependency is exhausted, so the proxy cannot obtain a response in time.
3. Incorrect upstream configuration: The proxy targets the wrong host, port, container address, Unix socket, or application path.
4. Socket or internal firewall access failure: The proxy cannot reach the backend because of socket permissions, network policy, a firewall, or a security-group change.
5. Invalid or oversized backend response: The application sends malformed output, an unusable status line, or headers larger than the proxy can accept.
6. CDN-to-origin failure: A CDN cannot reach the origin, is blocked by the origin firewall, or cannot establish the HTTPS connection expected by its origin configuration.

How to fix it

1. Identify where the 502 is generated

Check whether the error page is branded by Nginx, Apache, Cloudflare, a hosting platform, or another intermediary. Determine whether all routes fail or only one application path, and record the failure time and affected URL. This helps match the request to the correct logs.

2. Check the backend process and its logs

With authorized server or hosting-panel access, check whether the application process is running and accepting work. Review its logs for crash loops, fatal application errors, out-of-memory termination, missing dependencies, or startup failures.

For example, a read-only service check might be:

systemctl status php8.2-fpm
systemctl status nginx
pm2 status

Use the installed PHP-FPM version and process manager rather than copying these names unchanged. If the backend is stopped or crash-looping, fix the underlying cause first. Only then consider restarting the affected service through your normal change procedure; a restart can interrupt requests and remove useful runtime context, so confirm authorization and capture relevant logs beforehand.

3. Read the proxy error log

Match the log timestamp to a failed request. For Nginx, inspect the configured error log, commonly /var/log/nginx/error.log. For Apache using mod_proxy or mod_proxy_fcgi, inspect the Apache error log.

Useful distinctions include:

• connect() failed: the proxy cannot reach the configured upstream.
• upstream timed out: the backend or one of its dependencies is too slow or overloaded.
• upstream sent too big header: response headers exceed the configured proxy buffers.
• An error reading the status line: the backend closed the connection or returned an invalid response.

The exact log location and message format depend on the server and hosting platform.

4. Verify the upstream host, port, or socket

Review the reverse-proxy configuration. In Nginx, check the proxy_pass or upstream block. In Apache, check ProxyPass, ProxyPassMatch, and the PHP-FPM connection settings.

Use a read-only listener check and a local request where appropriate:

ss -tlnp
curl http://127.0.0.1:PORT

Replace PORT with the configured application port. If the application uses a Unix socket, verify that the path exists and that the proxy process can access it. For PHP-FPM, the pool’s listen setting must match the address or socket configured in Apache or Nginx. Do not expose an internal test endpoint publicly just to perform this check.

5. Investigate overload, dependencies, and timeouts

If the backend is running but failures coincide with traffic spikes or slow requests, check CPU, memory, worker counts, database connections, queue depth, and hosting-panel resource limits. A process may be running while unable to accept additional work.

Do not increase proxy timeouts or buffer sizes without evidence. If the log identifies oversized headers, inspect the application’s response and review the relevant Nginx proxy_buffer_size and proxy_buffers settings. If a configuration change is required, validate it and apply it through the approved change procedure rather than reloading a production proxy without authorization.

6. Compare the origin with the CDN path

When Cloudflare or another CDN is in front of the site, test the origin directly using the correct origin address and Host header, with authorization to do so. Compare the result with the public request.

• The origin also fails: investigate the application, proxy, socket, port, firewall, and resource conditions at the origin.
• The origin works but the CDN fails: check CDN-to-origin firewall rules, origin reachability, routing, and the CDN’s origin SSL/TLS mode. Confirm that the origin presents the protocol and certificate configuration the CDN expects.

7. Retest after the cause is corrected

First confirm that the origin returns the expected response. Then test the request through the reverse proxy or CDN. If only some URLs fail, compare their application routes, response size, authentication requirements, and backend dependencies instead of treating the issue as a general outage.

8. Check hosting-panel limits

On cPanel, Plesk, or similar shared hosting, review PHP-FPM and resource-usage logs. The account may be hitting a provider-enforced process, memory, or concurrency limit. If the limit cannot be changed, give the host the failure timestamps, affected route, and relevant log message so it can inspect infrastructure-level records.

Prevention & how to verify the fix

• Run the application under process supervision and monitor repeated crashes instead of relying only on automatic restarts.
• Monitor memory, CPU, worker usage, database connections, queue depth, and hosting-panel limits before they affect requests.
• Set deliberate, compatible timeouts between the application, proxy, load balancer, and CDN; do not use longer timeouts to conceal an unhealthy backend.
• Verify the expected application port or socket after deployments and configuration changes.
• Test representative routes directly against the origin and through the CDN after changes to origin TLS, firewall rules, or proxy configuration.
• Retain proxy and application logs with synchronized timestamps so intermittent 502 responses can be matched to backend events.
• Document the responsible service, upstream address, socket permissions, and approved recovery procedure for the environment.

Frequently asked questions