Nginx PHP 8.2 Upstream Header Premature Close

Threat/Impact Level: HIGH | Downtime Risk: HIGH | Time to Fix: 15–45 mins depending on root cause

TL;DR

• What broke: PHP-FPM 8.2 worker died, timed out, or was OOM-killed mid-request before sending a single response header byte to Nginx, causing Nginx to emit a 502.
• How to fix it: Align fastcgi_read_timeout in Nginx with request_terminate_timeout in FPM, tune pm worker settings to prevent pool exhaustion, and audit PHP 8.2 fatal errors in /var/log/php-fpm/www-error.log.
• Shortcut: Use our Client-Side Sandbox above to paste your nginx.conf and www.conf — it auto-detects the timeout mismatch and refactors both files locally without sending your config anywhere.

2024/01/15 03:42:17 [error] 1234#1234: *5678 upstream prematurely closed connection
while reading upstream response header from upstream,
client: 10.0.1.45, server: app.example.com,
request: "POST /api/process HTTP/1.1",
upstream: "fastcgi://unix:/run/php/php8.2-fpm.sock",
host: "app.example.com"

How to Fix It

Step 1 — Identify the Actual Root Cause

Before touching config, check these in order:

# 1. Check for OOM kills
sudo dmesg | grep -i 'killed process' | grep php

# 2. Check PHP-FPM worker crash logs
sudo tail -n 100 /var/log/php8.2-fpm.log
sudo tail -n 100 /var/log/nginx/error.log | grep upstream

# 3. Check pool status (if pm.status_path is enabled)
curl http://127.0.0.1/fpm-status?full

# 4. Check active worker count vs max_children
ps aux | grep php-fpm | wc -l

Basic Fix — Timeout Alignment

The most common cause: fastcgi_read_timeout in Nginx is shorter than the actual PHP execution time, or request_terminate_timeout in FPM kills the worker before Nginx gives up.

# /etc/nginx/sites-available/app.conf

 location ~ \.php$ {
     fastcgi_pass unix:/run/php/php8.2-fpm.sock;
     fastcgi_index index.php;
     include fastcgi_params;
     fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
-    fastcgi_read_timeout 60;
-    fastcgi_send_timeout 60;
-    fastcgi_connect_timeout 60;
+    fastcgi_read_timeout 300;
+    fastcgi_send_timeout 300;
+    fastcgi_connect_timeout 10;
+    fastcgi_buffers 16 16k;
+    fastcgi_buffer_size 32k;
 }

# /etc/php/8.2/fpm/pool.d/www.conf

- request_terminate_timeout = 0
+ request_terminate_timeout = 290
+ request_slowlog_timeout = 10s
+ slowlog = /var/log/php8.2-fpm-slow.log

- pm = dynamic
- pm.max_children = 5
- pm.start_servers = 2
- pm.min_spare_servers = 1
- pm.max_spare_servers = 3
+ pm = dynamic
+ pm.max_children = 50
+ pm.start_servers = 10
+ pm.min_spare_servers = 5
+ pm.max_spare_servers = 20
+ pm.max_requests = 500

Rule: fastcgi_read_timeout (Nginx) must always be greater than request_terminate_timeout (FPM). FPM should terminate the worker first, cleanly, before Nginx gives up and 502s.

Enterprise Best Practice — Layered Hardening

# /etc/php/8.2/fpm/pool.d/www.conf

+ ; Prevent runaway workers from holding connections indefinitely
+ request_terminate_timeout = 290
+
 + ; PHP 8.2 — explicitly set memory limit per pool, not just php.ini
 + php_admin_value[memory_limit] = 256M
+
 + ; Catch worker crashes and restart automatically
 + emergency_restart_threshold = 10
 + emergency_restart_interval = 1m
 + process_control_timeout = 10s
+
 + ; Enable status endpoint for monitoring
 + pm.status_path = /fpm-status
 + ping.path = /fpm-ping

# /etc/php/8.2/fpm/php-fpm.conf

- error_log = /var/log/php8.2-fpm.log
- log_level = notice
+ error_log = /var/log/php8.2-fpm.log
+ log_level = warning
+ log_limit = 8192
+ ; Critical for PHP 8.2 TypeError fatals showing full stack
+ catch_workers_output = yes
+ decorate_workers_output = yes

For PHP 8.2 specifically — audit code for deprecated implicit type coercions:

- function processOrder(int $id) {
-     $result = fetchFromDB("SELECT * FROM orders WHERE id = " . $id);
+ function processOrder(int $id): array {
+     if (!is_int($id)) throw new \InvalidArgumentException('ID must be integer');
+     $result = fetchFromDB("SELECT * FROM orders WHERE id = " . $id);

💡 Tired of pasting proprietary infrastructure configs into public LLMs? Generic AI interfaces log your company's ARNs, connection strings, and private keys. StackEngine enforces client-side zero-trust boundaries—the sandbox above executes 100% locally in your browser. Drop your broken manifest above to redact secrets locally and synthesize deterministic patch drafts with your own API key.

(For CI/CD pipeline automation, install via npm i -g stackengine).

# Add to your CI pipeline (GitHub Actions / GitLab CI)
- name: Validate Nginx Config
  run: |
    docker run --rm -v $(pwd)/nginx:/etc/nginx nginx:stable nginx -t

- name: Validate PHP-FPM Config
  run: |
    php-fpm8.2 --test -y /etc/php/8.2/fpm/php-fpm.conf

#!/bin/bash
# ci/check-timeout-alignment.sh
NGINX_TIMEOUT=$(grep fastcgi_read_timeout nginx/app.conf | grep -oP '\d+')
FPM_TIMEOUT=$(grep request_terminate_timeout fpm/www.conf | grep -oP '\d+')

if [ "$NGINX_TIMEOUT" -le "$FPM_TIMEOUT" ]; then
  echo "FATAL: fastcgi_read_timeout ($NGINX_TIMEOUT) must be > request_terminate_timeout ($FPM_TIMEOUT)"
  exit 1
fi
echo "Timeout alignment OK: Nginx=$NGINX_TIMEOUT FPM=$FPM_TIMEOUT"

# prometheus/alerts/php-fpm.yml
groups:
  - name: php-fpm
    rules:
      - alert: FPMPoolNearlyExhausted
        expr: phpfpm_active_processes / phpfpm_max_children > 0.85
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "PHP-FPM pool at {{ $value | humanizePercentage }} capacity — 502s imminent"

# checkov custom check — enforce pm.max_children >= 20
from checkov.common.models.enums import CheckResult
from checkov.ansible.checks.base_ansible_check import BaseAnsibleCheck

class CheckFPMMaxChildren(BaseAnsibleCheck):
    def __init__(self):
        self.id = "CKV_ANSIBLE_FPM_001"
        self.name = "Ensure PHP-FPM pm.max_children is adequately sized"

    def check_resource_config(self, conf):
        max_children = conf.get("pm.max_children", 0)
        return CheckResult.PASSED if int(max_children) >= 20 else CheckResult.FAILED