CRITICAL

How to Fix 502 Bad Gateway in NGINX on Ubuntu 24.04 LTS

Quick Fix Summary

TL;DR

Restart PHP-FPM and NGINX, then check upstream service connectivity and error logs.

A 502 Bad Gateway indicates NGINX cannot communicate with its upstream server (like PHP-FPM or a backend app). This is a critical proxy failure that halts all traffic to your application.

Diagnosis & Causes

  • PHP-FPM or upstream application service is stopped.
  • NGINX and upstream service socket/file permissions are incorrect.
  • Upstream service is timing out or unresponsive.
  • NGINX proxy buffer or timeout values are too low.
  • Resource exhaustion (CPU, memory) on the upstream server.

    • Recovery Steps

    1

    Step 1: Immediate Service Restart & Status Check

    First, restart the core services to resolve transient failures and verify their state.

    bash 
    sudo systemctl restart php8.3-fpm nginx
sudo systemctl status php8.3-fpm nginx --no-pager -l
    2

    Step 2: Verify Upstream Connectivity

    Test if NGINX can reach the upstream service (PHP-FPM) via its configured socket or port.

    bash 
    sudo ss -lnp | grep -E '(php-fpm|9000)'
# If using a Unix socket:
sudo ls -la /var/run/php/php8.3-fpm.sock
# If using TCP:
sudo nc -zv 127.0.0.1 9000
    3

    Step 3: Inspect Critical Logs for Root Cause

    Check NGINX and PHP-FPM error logs for the specific failure message (connection refused, timeout, permission denied).

    bash 
    sudo tail -50 /var/log/nginx/error.log
sudo journalctl -u php8.3-fpm --since "5 minutes ago" --no-pager
    4

    Step 4: Validate NGINX Configuration

    Ensure NGINX configuration is syntactically correct and the upstream `fastcgi_pass` directive points to the right location.

    bash 
    sudo nginx -t
# Review your site config's fastcgi_pass directive:
sudo grep -r "fastcgi_pass" /etc/nginx/sites-enabled/
    5

    Step 5: Adjust NGINX Proxy Timeouts (If logs show timeouts)

    Increase proxy timeout values in your NGINX site config to prevent premature disconnection from slow upstreams.

    nginx 
    # Add inside your 'location' block handling PHP:
location ~ \.php$ {
    ...
    fastcgi_read_timeout 300;
    fastcgi_send_timeout 300;
    fastcgi_connect_timeout 75;
}
    6

    Step 6: Check System Resources

    Rule out system-level issues like memory exhaustion that could be killing the PHP-FPM processes.

    bash 
    free -h
top -bn1 | head -20
sudo systemctl status php8.3-fpm | grep -A 5 "CGroup"

    Architect's Pro Tip

    "For sporadic 502s, monitor `pm.max_children` in `/etc/php/8.3/fpm/pool.d/www.conf`. All children busy will cause new requests to queue and fail."

    Frequently Asked Questions

    I restarted services but the 502 error returns after a few minutes. What's next?

    This indicates a chronic resource or configuration issue. Enable slow PHP-FPM logging (`request_slowlog_timeout`), profile your application code for bottlenecks, and ensure `pm.max_children` is high enough for your traffic.

    My error log shows 'Connection refused to upstream'. What does this mean?

    NGINX cannot establish a connection. The upstream service (PHP-FPM, Gunicorn, etc.) is not listening on the configured socket/port. Verify the service is running and the `fastcgi_pass` or `proxy_pass` directive is correct.

    Related Linux Guides

    502 Bad Gateway

    How to Fix 502 Bad Gateway in Nginx/Apache on Ubuntu 24.04
    ImagePullBackOff

    Kubernetes Troubleshooting Guide: Diagnosing ImagePullBackOff on Linux Nodes
    EIO

    How to Fix Linux EIO