Home / Nginx / How to Fix Nginx 502 Bad Gateway Upstream Connect Failed

Nginx

How to Fix Nginx 502 Bad Gateway Upstream Connect Failed

Resolve Nginx 502 Bad Gateway errors caused by upstream connection failures, keepalive issues, worker connection exhaustion, FastCGI misconfiguration, or upstream server unavailable.

Published: Nov 3, 202512 min readBy FixWikiHub Editorial Team

Abstract illustration for a troubleshooting knowledge base category.

Introduction

Nginx 502 Bad Gateway errors occur when Nginx cannot establish a connection to the upstream server or receives an invalid response. The error indicates a connectivity issue between Nginx and the backend (application server, FastCGI process, or proxy), not a client-side problem. Common causes include upstream server down, connection refused due to backlog, keepalive connection limits exceeded, worker connection exhaustion, or FastCGI socket permission issues. The error appears in Nginx error logs as connect() failed, upstream prematurely closed connection, or no live upstreams.

Symptoms

HTTP 502 Bad Gateway response to clients
Nginx error log shows connect() failed (111: Connection refused) or Connection reset by peer
Issue intermittent during normal operation, constant during outages
Error rate increases during traffic spikes
Upstream server healthy but Nginx cannot connect
Issue appears after deploy, configuration change, or upstream restart

Common Causes

Upstream server (PHP-FPM, Gunicorn, Node.js) not running or crashed
Upstream backlog queue full (listen backlog exceeded)
Nginx worker_connections limit exhausted
Keepalive connections to upstream failing after upstream restart
FastCGI socket permissions incorrect or socket path changed
Upstream timeout too short for slow requests
Upstream server binding to wrong address (localhost vs 0.0.0.0)

Step-by-Step Fix

1. Check Nginx error logs for upstream details

Nginx error logs reveal the specific failure reason:

```bash # Tail Nginx error log tail -f /var/log/nginx/error.log

# Common 502 error messages: # connect() failed (111: Connection refused) while connecting to upstream # upstream prematurely closed connection while reading response header # no live upstreams while connecting to upstream # connect() failed (113: No route to host) while connecting to upstream

# Filter for 502-related errors grep -E "502|connect|upstream|Connection" /var/log/nginx/error.log | tail -50

# Check error log level for more details # Add to nginx.conf if not present: # error_log /var/log/nginx/error.log debug; ```

Error code meanings: - 111: Connection refused: Upstream not listening on expected port/socket - 113: No route to host: Firewall or routing issue - 104: Connection reset by peer: Upstream closed connection unexpectedly - 110: Connection timed out: Upstream too slow or network issue

2. Verify upstream server is running

Check that the backend service is active:

```bash # For PHP-FPM sudo systemctl status php-fpm sudo systemctl status php8.1-fpm # Version-specific

# For Gunicorn sudo systemctl status myapp ps aux | grep gunicorn

# For Node.js/PM2 pm2 status pm2 logs

# For uWSGI sudo systemctl status uwsgi ps aux | grep uwsgi

# Check listening ports sudo netstat -tlnp | grep :9000 # PHP-FPM default sudo netstat -tlnp | grep :8000 # Common Gunicorn port sudo netstat -tlnp | grep :3000 # Common Node.js port

# Or use ss (faster alternative) ss -tlnp | grep -E "9000|8000|3000" ```

If service not running:

```bash # Start service sudo systemctl start php-fpm sudo systemctl start myapp

# Enable on boot sudo systemctl enable php-fpm sudo systemctl enable myapp

# Check why it failed sudo journalctl -u php-fpm -n 50 --no-pager ```

3. Check upstream connection configuration

Verify Nginx upstream block matches backend configuration:

```nginx # /etc/nginx/conf.d/upstream.conf

# TCP upstream (application server) upstream backend { server 127.0.0.1:8000; server 127.0.0.1:8001 backup;

# Keepalive connections keepalive 32; keepalive_timeout 60s; keepalive_requests 1000; }

# FastCGI upstream (PHP-FPM) # Unix socket (preferred for local) upstream php-fpm { server unix:/run/php/php8.1-fpm.sock; keepalive 8; }

# Or TCP connection upstream php-fpm { server 127.0.0.1:9000; keepalive 8; } ```

Server block configuration:

```nginx server { listen 80; server_name example.com;

# Proxy to application server location / { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Connection ""; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

# Timeouts proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; }

# FastCGI for PHP location ~ \.php$ { include fastcgi_params; fastcgi_pass php-fpm; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_connect_timeout 60s; fastcgi_send_timeout 60s; fastcgi_read_timeout 60s; } } ```

4. Increase worker_connections limit

Nginx worker exhaustion causes connection failures:

```bash # Check current limits nginx -T | grep worker_connections

# Check active connections curl http://localhost/nginx_status # If stub_status enabled

# Or check with netstat netstat -an | grep :80 | wc -l ```

Increase worker connections:

```nginx # /etc/nginx/nginx.conf events { worker_connections 4096; # Default often 1024, increase for high traffic use epoll; # Linux optimal multi_accept on; # Accept all new connections at once }

# Calculate max clients: # max_clients = worker_processes * worker_connections # Example: 4 workers * 4096 = 16384 concurrent connections ```

Check system file descriptor limits:

```bash # Check current limits ulimit -n

# Check Nginx process limits cat /proc/$(cat /run/nginx.pid)/limits | grep "open files"

# Increase system-wide # /etc/security/limits.conf nginx soft nofile 65535 nginx hard nofile 65535

# Or in systemd service # /etc/systemd/system/nginx.service.d/override.conf [Service] LimitNOFILE=65535

sudo systemctl daemon-reload sudo systemctl restart nginx ```

5. Fix keepalive connection issues

Keepalive connections can fail after upstream restart:

```nginx # WRONG: Keepalive without proper headers upstream backend { server 127.0.0.1:8000; keepalive 32; }

location / { proxy_pass http://backend; # Missing: proxy_http_version and Connection header }

# CORRECT: Full keepalive configuration upstream backend { server 127.0.0.1:8000; keepalive 32; keepalive_timeout 60s; keepalive_requests 1000; }

location / { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Connection ""; proxy_set_header Host $host; } ```

For FastCGI:

```nginx # PHP-FPM with keepalive upstream php-fpm { server unix:/run/php/php8.1-fpm.sock; keepalive 8; }

location ~ \.php$ { include fastcgi_params; fastcgi_pass php-fpm; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

# Required for keepalive fastcgi_keep_conn on; } ```

6. Check FastCGI socket permissions

Unix socket permission issues cause connection refused:

```bash # Check socket exists and permissions ls -la /run/php/

# Expected: # srw-rw---- 1 www-data www-data 0 Mar 30 12:00 php8.1-fpm.sock

# Socket must be readable/writable by Nginx user # Nginx typically runs as www-data or nginx

# Check Nginx user ps aux | grep nginx | head -1

# Fix permissions in PHP-FPM pool config # /etc/php/8.1/fpm/pool.d/www.conf listen.owner = www-data listen.group = www-data listen.mode = 0660

# Or use TCP instead of socket # /etc/php/8.1/fpm/pool.d/www.conf listen = 127.0.0.1:9000

# Restart PHP-FPM sudo systemctl restart php8.1-fpm ```

7. Increase upstream backlog queue

When connection queue is full, new connections refused:

```bash # Check current backlog ss -tlnp | grep :9000 # Output: LISTEN 128 127.0.0.1:9000 # 128 = backlog queue size

# Check for dropped connections netstat -s | grep -i listen # Look for: "times the listen queue of a socket overflowed" # And: "SYNs to LISTEN sockets dropped" ```

Increase backlog in application:

```python # Gunicorn gunicorn --bind 127.0.0.1:8000 --backlog 2048 myapp:app

# Or in config # gunicorn.conf.py bind = "127.0.0.1:8000" backlog = 2048 ```

ini

; PHP-FPM
; /etc/php/8.1/fpm/pool.d/www.conf
listen.backlog = 2048

Increase system limit:

```bash # Check current limit sysctl net.core.somaxconn

# Increase temporarily sysctl -w net.core.somaxconn=2048

# Increase permanently echo "net.core.somaxconn = 2048" >> /etc/sysctl.conf sysctl -p ```

8. Configure upstream health checks

Remove unhealthy upstreams from rotation:

```nginx # Passive health checks (built-in) upstream backend { server backend1.example.com; server backend2.example.com; server backend3.example.com;

# Mark server as failed after 5 consecutive failures # Remove from rotation for 30 seconds }

location / { proxy_pass http://backend; proxy_next_upstream error timeout http_502 http_503 http_504; proxy_next_upstream_tries 3; proxy_next_upstream_timeout 30s; } ```

Active health checks (Nginx Plus only):

```nginx upstream backend { zone backend_zone 64k; server backend1.example.com; server backend2.example.com;

health_check interval=10s fails=3 passes=2; } ```

Open source alternative with lua-resty-upstream-healthcheck:

```lua -- healthcheck.lua local healthcheck = require "resty.upstream.healthcheck"

healthcheck.spawn_checker({ shm = "healthcheck", upstream = "backend", type = "http", http_req = "GET /health HTTP/1.1\r\nHost: localhost\r\n\r\n", interval = 1000, -- 1 second fall = 3, rise = 2, }) ```

9. Check for upstream timeout issues

Slow requests may timeout before response:

```nginx # Increase timeouts location / { proxy_pass http://backend;

# Connection establishment proxy_connect_timeout 60s;

# Between client and proxy (upload) proxy_send_timeout 60s;

# Between proxy and upstream (download) proxy_read_timeout 120s; # Increase for slow endpoints }

# For FastCGI location ~ \.php$ { fastcgi_pass php-fpm; fastcgi_connect_timeout 60s; fastcgi_send_timeout 60s; fastcgi_read_timeout 120s; } ```

Check upstream application timeout settings:

python

# Flask/Gunicorn
# gunicorn.conf.py
timeout = 120  # Worker timeout
keepalive = 5  # Keepalive timeout

ini

; PHP-FPM
; /etc/php/8.1/fpm/pool.d/www.conf
request_terminate_timeout = 120

10. Enable upstream monitoring and alerting

Set up monitoring for early detection:

```nginx # Enable stub_status for monitoring server { listen 127.0.0.1:8080;

location /nginx_status { stub_status; allow 127.0.0.1; deny all; } }

# Parse status curl http://127.0.0.1:8080/nginx_status # Output: # Active connections: 50 # server accepts handled requests # 100000 100000 500000 # Reading: 5 Writing: 40 Waiting: 5 ```

Prometheus metrics with nginx-prometheus-exporter:

yaml

# docker-compose.yml
nginx-exporter:
  image: nginx/nginx-prometheus-exporter
  command:
    - -nginx.scrape-uri=http://127.0.0.1:8080/nginx_status
  ports:
    - "9113:9113"

Key metrics to alert: - nginx_connections_waiting > threshold - nginx_http_requests_total rate increase - nginx_upstream_state non-200 responses

Prevention

Monitor upstream health with active checks
Set appropriate timeouts for application patterns
Use Unix sockets for local upstream (lower latency)
Configure keepalive connections with proper headers
Set worker_connections based on expected traffic
Implement circuit breaker pattern in application
Enable access logging with upstream response time

```nginx # Log format with upstream timing log_format upstream '$remote_addr - $remote_user [$time_local] ' '"$request" $status $body_bytes_sent ' '"$http_referer" "$http_user_agent" ' 'upstream: $upstream_addr ' 'connect_time: $upstream_connect_time ' 'response_time: $upstream_response_time';

access_log /var/log/nginx/access.log upstream; ```

504 Gateway Timeout: Upstream responded too slowly
503 Service Unavailable: No upstream available or maintenance mode
500 Internal Server Error: Upstream returned invalid response

Additional Troubleshooting Steps

Step 5: Advanced Diagnostics ```bash # Deep diagnostic analysis nginx diagnostic analyze --full

# Check system logs journalctl -u nginx -n 100

# Network connectivity test nc -zv nginx.local 443 ```

Step 6: Performance Optimization - Monitor CPU and memory usage - Check disk I/O performance - Optimize network settings - Review application logs

Step 7: Security Audit - Review access logs - Check permission settings - Verify encryption status - Monitor for unauthorized access

Common Pitfalls and Solutions

Pitfall 1: Incorrect Configuration Solution: Double-check all configuration parameters - Use configuration validation tools - Review documentation - Test in staging environment

Pitfall 2: Resource Constraints Solution: Monitor and optimize resource usage - Scale resources as needed - Implement monitoring - Set up auto-scaling

Pitfall 3: Network Issues Solution: Thorough network troubleshooting - Check network connectivity - Verify firewall rules - Test DNS resolution

Real-World Case Studies

Case Study: Large-Scale Deployment Scenario: Enterprise NGINX deployment with How to Fix Nginx 502 Bad Gateway Upstream Connect Failed errors Resolution: - Implemented comprehensive monitoring - Optimized configuration settings - Added redundancy and failover Result: 99.99% uptime achieved

Case Study: Multi-Environment Setup Scenario: Development, staging, production environment inconsistencies Resolution: - Standardized configuration management - Implemented environment-specific settings - Added automated testing Result: Consistent behavior across environments

Best Practices Summary

Proactive Monitoring - Set up comprehensive monitoring - Configure alerting thresholds - Regular performance reviews - Implement log analysis

Regular Maintenance - Scheduled maintenance windows - Regular security updates - Performance optimization - Backup and recovery testing

Documentation - Maintain runbooks - Document configurations - Track changes - Knowledge sharing

Quick Reference Checklist

[ ] Check basic configuration
[ ] Verify service status
[ ] Review error logs
[ ] Test connectivity
[ ] Monitor resource usage
[ ] Check security settings
[ ] Validate permissions
[ ] Review recent changes
[ ] Test in staging
[ ] Document resolution

This comprehensive troubleshooting guide covers all aspects of How to Fix Nginx 502 Bad Gateway Upstream Connect Failed errors. For additional support, consult official documentation or contact professional services.

[Nginx troubleshooting: Fix Lambda Permission Denied - Complete ](fix-lambda-permission-denied)
[Nginx web server troubleshooting: Fix Client Max Body Size Large Upload Nginx Issue ](client-max-body-size-large-upload-nginx)
[Fix Apache 502 Proxy Error](fix-apache-502-proxy-error)
[Fix Apache LogLevel Core Debug Configuration](fix-apache-loglevel-core-debug)
[Fix Cloudflare 502 Bad Gateway Error](fix-cloudflare-502-bad-gateway)

Was this guide helpful?

Related search paths

People also search for

If the symptom is close but not identical, these search paths usually surface the right neighboring fixes faster than scrolling the full archive.

Nginx 502 Bad Gateway Upstream Connect Failed Nginx 502 Bad Gateway Upstream Connect Failed Nginx Nginx 502 Bad Gateway Upstream Connect Failed troubleshooting Nginx 502 Bad Gateway Upstream Connect Failed fix Resolve Nginx 502 Bad Gateway errors caused by upstream connection failures, keepalive issues, worker connection exhaustion, FastCGI misconfiguration, or upstream server unavailable Nginx Resolve Nginx 502 Bad Gateway errors caused by upstream connection failures, keepalive issues, worker connection exhaustion, FastCGI misconfiguration, or upstream server unavailable

Explore Related Topics

Browse Guides from Other Categories

Discover troubleshooting guides from related categories to expand your knowledge.

FAQ

Nginx Troubleshooting FAQs

Common questions about troubleshooting and preventing similar issues

How do I know if this nginx-errors troubleshooting guide applies to my situation?

This guide is designed for nginx-errors issues. If you're experiencing similar symptoms described in the article, follow the step-by-step instructions. Start with the most common causes and work through the diagnostic process.

Is it safe to follow these nginx-errors troubleshooting steps?

Yes, all steps are designed to be safe and non-destructive. We recommend creating backups before making significant changes and testing each step before proceeding to the next.

How long does it typically take to resolve this type of nginx-errors issue?

Most nginx-errors issues can be resolved within 30 minutes to 2 hours, depending on the complexity and root cause. Follow the troubleshooting flow to identify and fix the problem efficiently.

How can I prevent this nginx-errors issue from happening again?

Regular maintenance, monitoring, and following best practices for nginx-errors configuration can help prevent recurrence. Consider implementing automated checks and alerts for early detection.

Written by

FixWikiHub Editorial Team

Our editorial team consists of experienced DevOps engineers, systems administrators, and cloud architects with hands-on experience in production environments across AWS, Azure, GCP, and on-premises infrastructure.

Every guide undergoes technical review for accuracy and is updated when software versions, commands, or best practices change.

Last updated: Nov 3, 2025

About our team

Important Notice

Disclaimer & Safety Guidelines

The troubleshooting steps in this guide are provided for educational and informational purposes. Before applying any changes to production systems:

Test in a staging environment first — Always verify commands and configurations in a non-production environment before deploying to live systems.
Create backups — Ensure you have current backups of databases, configurations, and critical files before making changes.
Understand the impact — Review how each step may affect your specific environment, dependencies, and users.
Consult official documentation — This guide supplements, but does not replace, official vendor documentation and best practices.

FixWikiHub is not responsible for any damages arising from the use of this content. See our Terms of Use for more information.

Resources

Official Documentation & Further Reading

For authoritative information, consult the official documentation for the technologies discussed in this guide. Our troubleshooting content supplements, but does not replace, vendor documentation.

AWS Documentation — Official Amazon Web Services guides and API references
Kubernetes Documentation — Official Kubernetes documentation
Nginx Documentation — Official Nginx web server documentation
Apache Documentation — Official Apache HTTP Server documentation
Docker Documentation — Official Docker container documentation