FaultForge

502

502 Bad Gateway

Diagnose a 502 Bad Gateway by checking the proxy, CDN, upstream app, PHP-FPM, timeouts, and server logs before changing DNS.

Start here

Visitor check Confirm whether the 502 is local or public Confirm whether the error is local to one browser, network, or device. Site owner path Identify the layer returning the 502 Check public impact, recent changes, and the first layer that returned the error. Server operator path Check gateway logs and upstream health Use logs, upstream health, and rollback evidence before changing configuration.

Quick Answer

Start by identifying which layer generated the 502. If every browser and network sees it, check the CDN or gateway response headers, then the reverse proxy logs and upstream service health. If nginx is involved, open nginx upstream checks. If WordPress is involved, open WordPress PHP and plugin checks. If the only clue is Chrome, use Chrome visitor triage before changing server configuration.

502 vs 500 vs 504

A 502 means a gateway or proxy could not get a valid response from an upstream. A 500 usually means the application generated its own server error. A 504 means the gateway waited too long and received no response in time. That distinction matters because DNS changes rarely fix a real 502; the failing handoff is usually CDN, reverse proxy, origin, upstream runtime, or database latency.

Layer checklist

LayerSymptomCheck
CDNError page is CDN-brandedCompare edge headers and origin reachability before bypassing cache.
Reverse proxynginx or gateway wordingUse the 502 tracing guide.
App runtimePHP-FPM, Node, or container unavailableCheck service status, upstream socket/port, and app logs.
DatabaseApp times out waiting for DBUse the database troubleshooting hub.

What to send support

Include the affected URL, timestamp and timezone, response headers or request ID, recent changes, CDN/origin branding, and the first matching proxy or app log line.

Diagnosis

Symptoms

  • The browser shows 502 Bad Gateway, Bad Gateway, or a CDN-branded 502 page.
  • Other pages on the same host may still work if only one upstream route is broken.
  • Proxy logs often mention upstream timeouts, connection refused, invalid headers, or prematurely closed connections.

Common causes

  • The upstream application, PHP-FPM pool, Node process, or container is down or restarting.
  • The reverse proxy points at the wrong host, port, socket, protocol, or upstream name.
  • A CDN or load balancer cannot reach the origin or receives a bad response from it.
  • Recent deployments changed routing, headers, TLS, DNS, or health checks.
  • The upstream is overloaded and times out before the gateway receives a valid response.

Diagnostic Checklist

  1. Test from another network or with curl -I to separate local browser issues from public failures.
  2. Record response headers, timestamp, hostname, request ID, and whether the page is CDN-branded.
  3. Check gateway and upstream logs for the same timestamp.
  4. Confirm the upstream service is listening where the proxy expects it.
  5. Review deployments, DNS changes, config reloads, and cache purges made shortly before the first 502.

Fixes

Confirm whether the 502 is local or public

  • 5 minutes
  • Risk: low
  • Anyone
  • Browser, DNS

Avoid server changes until you know whether the failure reproduces outside one browser profile.

  1. Open the URL in another browser or private window.
  2. Try a different network, such as a mobile hotspot.
  3. Run curl -I https://example.com/path from a terminal or remote shell.
  4. Compare the status code, response headers, and error page branding.
Expected result

The failure is classified as local-only, network-specific, or public.

If it failed

If only one browser fails, clear site data, browser DNS cache, and extensions before touching the server.

Verify

Repeat the URL test from two paths and save the headers.

Rollback

No production rollback is needed for this read-only check.

Was this fix useful?

Identify the layer returning the 502

  • 10 minutes
  • Risk: low
  • Site owner
  • CDN, proxy, gateway

Use headers and logs to find the first system that generated the bad gateway response.

  1. Capture response headers and any request ID shown by the CDN, load balancer, or gateway.
  2. Check provider status pages if the response is CDN-branded.
  3. Compare the public URL with a direct origin test when that is safe and allowed.
  4. Map the first failing hop before editing config.
Expected result

You know whether the 502 came from the CDN, load balancer, reverse proxy, or upstream app.

If it failed

If headers are hidden, use access logs and provider request IDs instead.

Verify

The same request ID should appear in the layer that generated the response.

Rollback

Remove any temporary direct-origin test routes after verification.

Was this fix useful?

Check gateway logs and upstream health

  • 15 minutes
  • Risk: medium
  • Host admin
  • nginx, PHP-FPM, app runtime

Confirm the upstream exists, listens on the expected socket or port, and can return a valid response.

  1. Search nginx, load balancer, or gateway error logs around the failing timestamp.
  2. Check service status for PHP-FPM, Apache, Node, containers, or the application runtime.
  3. Verify sockets, ports, permissions, and upstream names match the active config.
  4. Restart only the failed upstream after capturing the log evidence.
Expected result

The upstream returns a valid response and the gateway stops logging upstream errors.

If it failed

If the upstream immediately fails again, inspect application logs before repeated restarts.

Verify

Reload the failing URL and watch the gateway log for a clean request.

Rollback

Restore the previous proxy config if a change made broader routes fail.

Was this fix useful?

Roll back the smallest recent change

  • 15-30 minutes
  • Risk: medium
  • Developer
  • Deployments, DNS, config

Reverse one likely change instead of stacking blind edits across layers.

  1. List deploys, plugin changes, config reloads, DNS edits, and cache purges made before the first 502.
  2. Choose the smallest reversible change that touches the failing layer.
  3. Preserve logs and current config before reverting.
  4. Apply the rollback through the normal deployment or hosting system.
Expected result

The failing URL recovers or the error changes to a narrower, actionable failure.

If it failed

If nothing changes, restore the current state and continue layer-by-layer diagnosis.

Verify

Test the broken URL and a known-good URL after rollback.

Rollback

Record the rollback time and exact version or setting restored.

Was this fix useful?

Platform notes

In nginx environments, 502 usually points at upstream connectivity, FastCGI sockets, proxy targets, timeouts, or service health. In WordPress environments, it often follows PHP-FPM crashes, plugin fatal errors, database pressure, or host-level resource limits.

FAQ

Is a 502 Bad Gateway a browser problem?

Usually no. The browser is displaying a response generated by a gateway or proxy. Browser checks are still useful to prove whether the error is local to one profile or network.

Should I restart nginx first?

Only after checking the log line. If the upstream is down, restarting nginx will not fix the actual failing service and may hide evidence.

Can DNS cause a 502?

Yes, when a CDN, load balancer, or proxy points to the wrong origin hostname or cached DNS answer. Browser DNS problems more often produce DNS errors instead of a true HTTP 502.

Review notes

Last reviewed
2026-05-05
Reviewed by
FaultForge Editorial Team, Web operations reviewer
Tested on

HTTP status checks, access and error log review, server response headers, recent deployment review, and safe rollback verification.

Sources