How to Diagnose and Fix Nginx 502 Bad Gateway Errors

Why Nginx Shows 502 Bad Gateway

Most 502 errors are not caused by Nginx itself but by problems in the upstream (backend) servers. When a backend host crashes, times out, or returns an unexpected response, Nginx forwards the generic "502 Bad Gateway" message to the client.

Trigger Conditions

The proxy_next_upstream directive controls when Nginx switches to another upstream server. Its default value is error timeout, but a more exhaustive setting often used is:

proxy_next_upstream error timeout invalid_header http_500 http_503;

Including http_500 makes Nginx treat a backend 500 response as a reason to try the next server, which can mask PHP errors as 502 responses.

Step 1 – Check FastCGI Process Availability

Run the following command to see how many PHP‑FastCGI processes are currently running:

netstat -anpo | grep "php-cgi" | wc -l

If the number of active FastCGI processes is close to the configured limit, increase the limit in your PHP‑FPM configuration.

Step 2 – Increase FastCGI Timeouts

When PHP scripts take longer than Nginx’s default wait time, extend the FastCGI timeout values in nginx.conf:

http { ... fastcgi_connect_timeout 300; fastcgi_send_timeout 300; fastcgi_read_timeout 300; ... }

Adjust the numbers according to your application’s needs.

Adjust php‑fpm Limits

Two key parameters in php-fpm.conf often cause intermittent 502 errors: max_children – maximum number of child processes. max_requests – number of requests a child handles before being recycled (default 500).

On a high‑traffic server, set them to larger values, for example:

<value name="max_children">5120</value> <value name="max_requests">600</value>

After editing, restart php‑fpm.

Increase Buffer Sizes

If the error log shows "pstream sent too big header while reading response header from upstream" , enlarge Nginx’s buffer settings. Keeping only the essential buffers— client_header_buffer_size and fastcgi_buffer_size —often resolves the issue.

Configure request_terminate_timeout

The request_terminate_timeout directive mirrors PHP’s max_execution_time. Setting it to 0s disables the timeout (unlimited execution), but a modest value such as 5s can prevent runaway scripts while still avoiding 502 errors.

Summary of Common Fixes

Verify FastCGI process count and raise pm.max_children if needed.

Increase FastCGI connect, send, and read timeouts.

Raise max_requests or set it to 0 to stop frequent child restarts.

Expand Nginx buffer sizes to accommodate large headers.

Adjust request_terminate_timeout to match application requirements.

Applying these adjustments typically eliminates the intermittent 502 Bad Gateway responses caused by backend overload or misconfiguration.