Nginx Nginx Web & Reverse Proxy Error 502: 502 Bad Gateway
HTTP status 502 Bad Gateway indicates that Nginx, acting as a reverse proxy or load balancer, received an invalid response or no response at all from the upstream backend server (PHP-FPM, Node.js, Python Gunicorn, or Go microservice).
Hardware Diagnostic Matrix
Spec Ref #8b7ffee3Required Diagnostic Tools & Instrumentation
Multimeter Probing Targets & Circuit Tolerances
Bench Calibrated ±5%| Test Point / Circuit | Target Nominal Spec | Expected State | Fault Condition |
|---|---|---|---|
| Main Logic DC Bus | 3.3V / 5.0V DC (±0.1V) | Stable DC Potential | <2.9V (Brownout / Sag) |
| Thermistor / NTC Sensor | 10kΩ - 100kΩ @ 25°C | Smooth Thermal Curve | 0Ω (Short) or ∞ (Open) |
| Safety Ground / PE Continuity | < 0.5Ω Resistance | Solid Earth Bond | > 1.0Ω (Floating Chassis) |
Common Symptoms & Fault Manifestations
- Web browser displays generic '502 Bad Gateway' with 'nginx' footer
- Website visitors cannot access dynamic pages, while static CSS/JS may still load
- Nginx `error.log` shows 'connect() failed (111: Connection refused)' or 'connect() to unix:/var/run/php/php-fpm.sock failed'
Root Causes & System Failure Modes
Upstream backend service (PHP-FPM, Node.js PM2, Gunicorn, Docker backend) is stopped or crashed
PHP-FPM pool max_children reached, freezing incoming request queue
Mismatched upstream socket path or port configuration in `proxy_pass` or `fastcgi_pass`
PHP or Node.js execution timeout exceeded (`request_terminate_timeout` or `proxy_read_timeout`)
High-Voltage & Mechanical Safety Isolation
Prior to opening access panels, disconnecting terminals, or probing wiring, perform complete lock-out / tag-out (LOTO). Disconnect all AC mains, DC string isolators, and lithium battery banks. Allow internal smoothing capacitors at least 3 to 5 minutes to dissipate stored residual energy below safe threshold (<30VDC).
Step-by-Step Diagnostic & Resolution Procedure
Examine Nginx Error Log
Tail the error log to pinpoint the exact failure reason: `sudo tail -n 50 /var/log/nginx/error.log`. Look for 'Connection refused' or 'No such file or directory'.
Check Upstream Backend Service Status
If using PHP: `sudo systemctl status php8.2-fpm` (or your PHP version). If using Node.js: `pm2 status` or `systemctl status node-app`. If inactive, restart the service: `sudo systemctl restart php8.2-fpm`.
Verify Socket Path or Port in Nginx Config
Inspect your site configuration (`/etc/nginx/sites-available/`). Ensure the `fastcgi_pass` socket path matches the active PHP-FPM `listen` directive in `/etc/php/8.2/fpm/pool.d/www.conf`.
Increase Buffer & Timeout Settings (For Heavy Requests)
If large database exports cause 502 timeouts, add to your `location` block: `fastcgi_read_timeout 300;` and `proxy_read_timeout 300;`.
Hardware Reset & Fault Clear Sequence
Controller ProcedurePrevention & Routine Maintenance Guidelines
- Tune PHP-FPM `pm.max_children` and `pm.start_servers` to avoid worker pool starvation
- Use process managers like systemd or PM2 with auto-restart policies on failure
- Set up uptime monitoring (e.g. UptimeKuma, Datadog) to alert when backends stall
Frequently Asked Diagnostic Questions
What does error code 502 indicate on Nginx Nginx Web & Reverse Proxy?
HTTP status 502 Bad Gateway indicates that Nginx, acting as a reverse proxy or load balancer, received an invalid response or no response at all from the upstream backend server (PHP-FPM, Node.js, Python Gunicorn, or Go microservice). In engineering telemetry, it indicates 502 bad gateway requiring circuit verification.
What are the primary triggers causing error 502?
Diagnostic bench telemetry isolates the following common root causes: Upstream backend service (PHP-FPM, Node.js PM2, Gunicorn, Docker backend) is stopped or crashed; PHP-FPM pool max_children reached, freezing incoming request queue; Mismatched upstream socket path or port configuration in `proxy_pass` or `fastcgi_pass`; PHP or Node.js execution timeout exceeded (`request_terminate_timeout` or `proxy_read_timeout`).
How do I reset and clear Nginx error 502?
Validate configuration syntax with `sudo nginx -t` and then reload gracefully using `sudo systemctl reload nginx`. If the error status repeats immediately after clearing, discontinue clearing and test circuit continuity.
Can I safely resolve error 502 without specialized shop tooling?
This fault is graded as Easy difficulty with High severity. Standard diagnostics require an insulated digital multimeter and appropriate hand tools. Always observe high-voltage isolation procedures.