FaultForge

502

502 Bad Gateway in nginx

Fix nginx 502 errors by checking upstream health, sockets, proxy_pass targets, PHP-FPM, timeouts, and nginx error logs.

Start here

Server operator path Match nginx upstream targets to active services Use logs, upstream health, and rollback evidence before changing configuration.

Quick Answer

For nginx, a 502 usually means nginx accepted the public request but could not get a valid response from the configured upstream. Check the active server block, the upstream or proxy_pass target, PHP-FPM socket or port, service health, and the exact nginx error log line.

Read the upstream message first

For nginx, a 502 is usually explained by the error log. Common lines include connect() to unix:/run/php/php-fpm.sock failed (2: No such file or directory), connect() failed (111: Connection refused) while connecting to upstream, or upstream timed out while reading response header from upstream. Each phrase points to a different fix.

Socket, TCP, and proxy_pass checks

Use the nginx upstream verification guide to compare the configured proxy_pass target with a listening service. Confirm whether the upstream is a TCP port such as 127.0.0.1:3000, a Unix socket such as /run/php/php-fpm.sock, or a named upstream block. Run nginx -t before any reload.

When to roll back

If the first 502 appeared immediately after a deployment, config change, PHP-FPM update, or container restart, preserve the failing config and logs, then roll back the smallest change and verify with curl -I from the proxy host.

Diagnosis

Symptoms

  • The error page is generated by nginx or a CDN in front of nginx.
  • The nginx error log mentions upstream connection refused, timed out, invalid header, no live upstreams, or prematurely closed connection.
  • Reloading nginx does not help if the upstream service is still down or misaddressed.

Common causes

  • proxy_pass points at the wrong protocol, host, port, or path.
  • PHP-FPM socket path or permissions do not match nginx config.
  • The upstream service is stopped, overloaded, restarting, or listening on a different interface.
  • A deploy changed headers, buffering, TLS, or timeout behavior between nginx and the upstream.

Diagnostic Checklist

  1. Run nginx -t before editing and after edits.
  2. Confirm the active server block for the failing hostname.
  3. Check the exact error log line for the failing timestamp.
  4. Confirm the upstream process is listening and reachable from the nginx host.

Fixes

Match nginx upstream targets to active services

  • 15 minutes
  • Risk: medium
  • Host admin
  • nginx

Correct mismatches between nginx config and the service that should answer.

  1. Find the active server, location, upstream, proxy_pass, or fastcgi_pass directive.
  2. Check the target host, port, socket path, protocol, and trailing slash behavior.
  3. Confirm the service listens at that target from the nginx server.
  4. Reload nginx only after nginx -t passes.
Expected result

nginx can connect to the intended upstream and the 502 stops for the route.

If it failed

If the target is correct but still fails, inspect upstream application logs and resource limits.

Verify

Watch the nginx error log while testing the URL.

Rollback

Restore the previous server block or upstream include if the reload breaks more routes.

Was this fix useful?

Repair PHP-FPM socket or pool failures

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

Fix WordPress and PHP sites where nginx cannot reach PHP-FPM.

  1. Check the PHP-FPM service and pool status.
  2. Compare fastcgi_pass with the active pool listen value.
  3. Check Unix socket ownership and parent directory permissions.
  4. Restart PHP-FPM if the pool is down, then reload nginx if config changed.
Expected result

PHP-FPM accepts requests from nginx and returns a PHP response.

If it failed

If PHP-FPM crashes again, check PHP fatal errors, memory limits, and slow logs.

Verify

Load a PHP health page or the failing URL and confirm no new socket errors appear.

Rollback

Revert socket path or pool edits if they affect other sites.

Was this fix useful?

Platform notes

When nginx is behind a CDN, prove whether the CDN or nginx generated the 502 before changing origin config. CDN request IDs and nginx access logs should line up for the same failing request.

FAQ

Does nginx -t prove the upstream works?

No. It only validates syntax. You still need to confirm the upstream process is running and reachable.

Should nginx or the upstream restart first?

Restart the failed upstream first when logs show connection failures. Reload nginx after config changes pass syntax validation.

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