Investigation of Nginx 502 Errors Caused by Large Response Headers from PHP‑FPM

The author, a PHP developer at Lianjia, encountered intermittent Nginx 502 errors reported as "upstream sent too big header while reading response from upstream" that only reproduced for specific requests.

Initial investigation suggested that PHP‑FPM warnings were being appended to the response header, inflating its size and potentially exceeding Nginx's fastcgi_buffer_size.

To verify this, the team captured traffic between Nginx and PHP‑FPM using tcpdump, both over TCP and Unix socket connections, and examined warning logs, error logs, and raw packet traces.

Analysis of the captured data showed that PHP‑FPM indeed forwards warning and error messages to Nginx, but the real trigger was incomplete response headers: PHP‑FPM sometimes sent a truncated header, causing Nginx's header parser to hit the end of the buffer and emit NGX_AGAIN, which resulted in the 502 error.

Systematic experiments were performed with fastcgi_buffer_size set to 1 KB, 2 KB, and 4 KB. For each setting, the team ran a stress script that gradually increased the size of warning messages, monitored tcpdump logs, and recorded whether a 502 occurred.

Results indicated that the size of the data sent by PHP‑FPM at the moment of failure was roughly constant across buffer sizes, and increasing fastcgi_buffer_size did not eliminate the risk of the "too big header" error. The buffer acts as a staging area rather than a strict limit.

Final conclusions: (1) PHP‑FPM forwards warnings/errors to Nginx; (2) fastcgi_buffer_size determines how Nginx reads the header in chunks but does not prevent oversized headers; (3) under certain conditions PHP‑FPM sends incomplete headers, leading Nginx to report 502; (4) enlarging fastcgi_buffer_size does not reduce the occurrence of this error.

The article ends with open questions about why PHP‑FPM omits headers, other possible causes of the error, and why only particular request parameters trigger the issue.