Nginx 502 Bad Gateway to PHP-FPM

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Users receive HTTP 502 responses, resulting in partial or full web application outage.

Environment & Reproduction

Ubuntu 20.04 LEMP stack with Nginx proxying PHP requests to php-fpm pool.

Root Cause Analysis

PHP-FPM socket/service unavailable, overloaded workers, or mismatched fastcgi endpoint configuration.

Quick Triage

Check nginx and php-fpm service health plus recent error log entries.

Step-by-Step Diagnosis

Validate socket path/permissions, process limits, and pool-level timeout/resource settings.

Solution – Primary Fix

Restore php-fpm service, align socket config, and tune pool values for workload.

Solution – Alternative Approaches

Switch to TCP upstream temporarily or route traffic to healthy backend nodes.

Verification & Acceptance Criteria

HTTP 502 rate drops to zero and request latency/error SLOs return to baseline.

Rollback Plan

Revert pool and nginx changes if they increase memory pressure or request failures.

Prevention & Hardening

Monitor pool saturation, implement health checks, and use staged config deployment.

Related Errors & Cross-Refs

`connect() to unix:/run/php/php7.4-fpm.sock failed`, upstream timeout, and worker exhaustion.

Related tutorial: View the step-by-step tutorial for Ubuntu 20.04 LTS.

View all Ubuntu 20.04 LTS tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

Nginx and PHP-FPM operational tuning docs for Ubuntu 20.04.