nginx 502 Bad Gateway: Complete Troubleshooting Guide for All Upstream Failures

Understanding nginx 502 Bad Gateway and Related Upstream Errors

When nginx returns 502 Bad Gateway, the server successfully received your HTTP request but could not obtain a valid response from the upstream server it was proxying to. This is one of several related failure modes:

• 502 Bad Gateway — upstream returned an invalid response or closed the connection unexpectedly
• 504 Gateway Timeout — upstream is alive but exceeded proxy_read_timeout before responding
• 502 with 'connection refused' — nothing is listening on the upstream address/port
• nginx not starting at all — the nginx process itself failed at boot

Identifying which variant you face is the essential first diagnostic step.

Step 1: Read the Exact Error Message in the Log

Always begin with nginx's error log:

tail -n 100 /var/log/nginx/error.log
# For a specific virtual host:
tail -n 100 /var/log/nginx/mysite.error.log

Key phrases and their root causes:

Step 2: Confirm the Upstream Process Is Running

For PHP-FPM:

systemctl status php8.2-fpm
ss -tlnp | grep 9000
# Or for a Unix socket:
ls -la /run/php/php8.2-fpm.sock

For Node.js, Gunicorn, or uWSGI:

systemctl status myapp
ps aux | grep -E 'node|gunicorn|uwsgi'
ss -tlnp | grep 3000   # adjust port to match your app

If the process is dead, restart it and watch the logs:

systemctl restart myapp
journalctl -u myapp -f

Step 3: Verify the proxy_pass Configuration

A mismatched port or address in the nginx config is a frequent cause of 502 after deployments. Example correct configuration:

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;   # must match the app's listening port
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Always test before reloading:

nginx -t && systemctl reload nginx

Step 4: Fix Timeout-Related 502 and 504 Errors

If the upstream is alive but slow (heavy database queries, external API calls), increase the timeout directives:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout  10s;
    proxy_send_timeout     60s;
    proxy_read_timeout    120s;
}

For WebSocket applications or long-polling endpoints, values up to 300s or higher may be appropriate.

Step 5: Diagnose nginx Service Not Starting

If systemctl start nginx fails immediately, run:

nginx -t                          # find config syntax errors — output shows file and line
journalctl -u nginx -n 50         # full systemd journal for the unit
ss -tlnp | grep ':80\|:443'      # another process already on the port?

Common causes of nginx failing to start:

• Port conflict: Apache or a previous nginx process holds port 80/443. Identify the owner with ss -tlnp | grep ':80' and stop it.
• Config syntax error: nginx -t will print the exact file and line number.
• Missing or expired SSL certificate: The path in ssl_certificate does not exist or Let's Encrypt certificate has expired.

Step 6: Fix Permission Denied on Unix Sockets

When nginx proxies to a PHP-FPM or uWSGI Unix socket, the nginx worker user must have read/write access to the socket file:

ls -la /run/php/php8.2-fpm.sock
# Expected: srw-rw---- 1 www-data www-data ...

Ensure nginx runs as the same user or group that owns the socket:

# /etc/nginx/nginx.conf
user www-data;

Configure PHP-FPM to set the socket permissions explicitly:

; /etc/php/8.2/fpm/pool.d/www.conf
listen.owner = www-data
listen.group = www-data
listen.mode  = 0660

Restart both PHP-FPM and nginx after changing ownership settings.

Step 7: Resolve nginx High CPU and Too Many Connections

nginx high CPU is typically caused by:

1. Too few worker processes — set worker_processes auto; to use all CPU cores automatically
2. Connection churn — the upstream connection is torn down and rebuilt for every request. Add keepalive to the upstream block:

upstream backend {
    server 127.0.0.1:3000;
    keepalive 64;   # number of idle connections to keep open per worker
}

For 'worker_connections are not enough' warnings, increase limits in /etc/nginx/nginx.conf:

worker_processes auto;
worker_rlimit_nofile 65535;

events {
    worker_connections 4096;
    use epoll;
    multi_accept on;
}

Also raise the OS-level file descriptor limit:

echo 'nginx  soft  nofile  65535' >> /etc/security/limits.conf
echo 'nginx  hard  nofile  65535' >> /etc/security/limits.conf
sysctl -w fs.file-max=200000
echo 'fs.file-max = 200000' >> /etc/sysctl.conf

Step 8: Investigate nginx Crash, Core Dump, and Out-of-Memory Kills

If nginx workers die unexpectedly:

# Check OOM killer activity
dmesg | grep -i 'oom\|killed process'
journalctl -k | grep nginx

# Check for core dump files
find /var/crash /tmp /var/log -name 'core*' 2>/dev/null

# Check crash signals in journal
journalctl -u nginx --since '2 hours ago' | grep -iE 'signal|crash|segfault|coredump'

For OOM kills: reduce the number of worker processes, add system swap, or increase RAM. For segfaults (core dumps), check the nginx version first — upgrade to the latest stable release. If crashes persist, disable third-party modules one by one. Analyze a core file with:

gdb /usr/sbin/nginx /path/to/core
(gdb) bt full

Step 9: Fix nginx Slow Response

Slowness unrelated to upstream processing can have several nginx-side causes:

1. DNS resolution latency — if proxy_pass uses a hostname, nginx resolves it at config load only. Use IP addresses directly or add a resolver directive.
2. Buffering misconfiguration — for streaming or large file transfers:

proxy_buffering off;
# or for large API responses:
proxy_buffer_size 128k;
proxy_buffers     4 256k;

3. Missing compression — enable gzip for text payloads:

gzip on;
gzip_min_length 1024;
gzip_types text/plain application/json application/javascript text/css;

4. Missing sendfile / TCP tuning for static asset serving:

http {
    sendfile       on;
    tcp_nopush     on;
    tcp_nodelay    on;
    keepalive_timeout 65;
}