A 502 from an NGINX reverse proxy usually calls for checking the upstream application and the matching error log. The web server may be reachable while the application behind it is stopped, listening elsewhere or returning an invalid response.
Find the failing hop
- Record the failing hostname, path and exact time.
- Determine whether the response comes from your NGINX server or another proxy in front of it.
- Read the corresponding NGINX error entry.
- Compare the configured upstream address, port and protocol with the application listener.
- Check the application’s service status and logs for the same interval.
| Clue | Investigation |
|---|---|
| Connection refused | Application is stopped or listening on another address or port |
| Permission denied on a socket | Socket ownership, mode and security policy |
| Upstream connection closes early | Application crash or protocol mismatch |
| Only one path fails | Its location rule and backend handler |
Test from the proxy’s environment
Where appropriate, make a small request directly to the configured upstream from the proxy host. Use the protocol the backend actually speaks. With containers, localhost refers to the current container or host namespace; it may not refer to the application container you intended.
Keep the backend restricted as designed. Opening its port publicly may hide a routing mistake while creating unwanted exposure. Compare the actual upstream configuration rather than copying a generic proxy block over the site.
Validate a targeted fix
sudo nginx -tThis checks NGINX configuration syntax and referenced files. If it succeeds after a reviewed change, reload using your distribution’s service manager. A syntax pass does not prove the backend responds correctly, so repeat the failing request and inspect fresh logs.
Use service startup diagnosis when the application is down. Check disk capacity if it cannot write logs or temporary files.
Sources and references
Hosting documentation. Publication and update dates reflect this edition.
Related articles
- Diagnosing a Linux Service That Will Not StartUse systemd status and the service journal to find the first failure before changing restart settings.2 min read
- Linux Disk Full: Checking Space, Inodes and the Right FilesystemFind the exhausted filesystem before removing data or expanding a VPS disk.2 min read
- VPS Monitoring: CPU, Memory, Disk and Useful AlertsConnect operating-system metrics to application symptoms and test the alert path before relying on it during an outage.3 min read
