Debian 12 NGINX 502 Bad Gateway with 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

Web requests return 502 errors, making PHP applications unavailable to users.

Environment & Reproduction

Triggered by PHP-FPM downtime, socket path mismatch, or process pool exhaustion.

Root Cause Analysis

NGINX cannot reach configured upstream because PHP-FPM socket or port is unavailable.

Quick Triage

Check PHP-FPM service state and current socket file presence before reloading NGINX.

Step-by-Step Diagnosis

Review nginx error.log, php-fpm logs, and fastcgi_pass target alignment.

Solution – Primary Fix

Start or repair PHP-FPM pool, align socket path in both configs, and reload services.

Solution – Alternative Approaches

Switch to TCP upstream with explicit listen address when socket path issues persist.

Verification & Acceptance Criteria

Application endpoints return HTTP 200 and error logs no longer show upstream failures.

Rollback Plan

Restore previous NGINX and PHP-FPM configuration versions from backup.

Prevention & Hardening

Add health checks for PHP-FPM pools and alert on worker saturation metrics.

Related Errors & Cross-Refs

connect to unix failed; upstream prematurely closed connection; primary script unknown.

Related tutorial: View the step-by-step tutorial for debian-12.

View all debian-12 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

NGINX FastCGI docs, PHP-FPM pool tuning guides, and Debian web stack references.