How to Fix 502 Bad Gateway in nginx on Ubuntu

What 502 Bad Gateway from nginx means

nginx is very often a reverse proxy: it accepts the visitor's request and passes it to something else that builds the page, such as PHP-FPM for WordPress, a Node.js app, a Python app server, or Apache on a Plesk server. A 502 Bad Gateway means nginx tried to hand the request over and got no valid response back. nginx itself is running fine, which is why it can show you the error page at all. The problem is the thing behind it, or the connection between the two.

The line under the heading, such as nginx/1.18.0 (Ubuntu), nginx/1.24.0 (Ubuntu), nginx/1.29.1 or nginx/1.30.2, only tells you which nginx build is installed. Ubuntu 20.04 and 22.04 ship 1.18.0, Ubuntu 24.04 ships 1.24.0, and higher numbers usually come from the nginx.org packages. The causes and fixes for a 502 are the same on all of them, so you do not need to upgrade nginx to fix it.

If the error page says cloudflare instead of nginx, the 502 came from Cloudflare failing to reach your server, which is a different check. The broader 502 errors guide covers CDN and host-level causes; this page is about the nginx server itself.

Why you are getting 502 Bad Gateway in nginx

Each cause leaves a recognisable message in /var/log/nginx/error.log. Match your log line to this table and you will usually know the fix before you open a config file.

The two most common causes on Ubuntu are a PHP upgrade that changed the socket name, for example from php8.1-fpm.sock to php8.3-fpm.sock after moving to Ubuntu 24.04, and a Node.js app that stopped after a reboot because nothing was set up to restart it.

How to diagnose it on Ubuntu

Work through these commands in order. Run them over SSH as a user with sudo rights.

1. Read the error log

sudo tail -n 50 /var/log/nginx/error.log

# Watch it live while you reload the failing page
sudo tail -f /var/log/nginx/error.log

If the site has its own log file, find it with sudo grep -R error_log /etc/nginx/sites-enabled/. On Plesk, each domain has its own proxy log at /var/www/vhosts/system/example.com/logs/proxy_error_log.

2. Find out what nginx is pointing at

sudo nginx -T 2>/dev/null | grep -nE "fastcgi_pass|proxy_pass|upstream"

This prints the socket path or address and port each site uses. Compare it with what is actually running.

3. Check the upstream is running

# PHP-FPM: which versions are installed and are they active?
ls /run/php/
systemctl status 'php*-fpm' --no-pager

# Node or another app on a port: is anything listening?
sudo ss -ltnp | grep -E ':3000|:8000|:8080'

# Apps run by pm2 or systemd
pm2 status
systemctl status myapp --no-pager

4. Test the upstream directly

# Bypass nginx and ask the Node app for a page
curl -sI http://127.0.0.1:3000/

# Check the PHP-FPM socket permissions
ls -l /run/php/php8.3-fpm.sock

If the direct request works but the site still gives 502, the problem is in the connection between nginx and the app: a wrong path, a wrong port, permissions, or buffers. If the direct request also fails, fix the app first. The app's own logs are the next stop, for example sudo journalctl -u php8.3-fpm -n 50 or pm2 logs.

The key configuration fixes

Point nginx at the right PHP-FPM socket

# /etc/nginx/sites-available/example.com
location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}

The socket name must match the installed PHP version exactly. After editing, always test the config before reloading, because a syntax error stops the reload:

sudo nginx -t && sudo systemctl reload nginx

Fix socket permissions in the PHP-FPM pool

; /etc/php/8.3/fpm/pool.d/www.conf
listen = /run/php/php8.3-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

The user directive at the top of /etc/nginx/nginx.conf is www-data on Ubuntu by default. If you changed it, the pool owner or group must match. Restart PHP-FPM with sudo systemctl restart php8.3-fpm after the change.

Give PHP-FPM enough workers

pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6

If the PHP-FPM log says server reached pm.max_children setting, requests are queuing. Work out a safe number by dividing the memory you can spare for PHP by the average size of one PHP process, which you can see with ps -o rss= -C php-fpm8.3. Setting it too high makes the server run out of memory, and the out-of-memory killer then causes more 502s.

Proxy a Node.js app correctly

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_buffer_size 16k;
    proxy_buffers 8 16k;
    proxy_busy_buffers_size 32k;
}

Use 127.0.0.1 rather than localhost. On some systems localhost resolves to the IPv6 address ::1 first, and an app listening only on IPv4 then refuses the connection. The buffer lines fix the too big header message; for PHP the equivalents are fastcgi_buffer_size 32k; and fastcgi_buffers 16 16k;.

Platform notes

• WordPress on Ubuntu. A 502 after a plugin update is usually a PHP fatal error or memory exhaustion that kills the worker. Check /var/log/php8.3-fpm.log and the site's PHP error log, and disable the plugin by renaming its folder in wp-content/plugins. See HTTP errors in WordPress.
• Node.js apps. Run the app under pm2 or a systemd service so it restarts after a crash or a reboot. With pm2, pm2 startup followed by pm2 save sets this up. See HTTP errors in Node.js.
• Plesk. nginx usually sits in front of Apache or PHP-FPM handlers that Plesk manages. Check the domain's proxy_error_log, then use Repair in Tools and Settings or plesk repair web example.com to rebuild configuration files. See HTTP errors in Plesk.
• Docker. Inside a container, 127.0.0.1 means the container itself. Use the service name from your compose file, such as proxy_pass http://app:3000;, and make sure both containers share a network.

A worked example

Example Bakery upgrades its server from Ubuntu 22.04 to 24.04. After the reboot, every page shows 502 Bad Gateway with nginx/1.24.0 (Ubuntu) underneath. The home page is cached as static HTML and still loads, which is confusing at first.

The error log has one line repeated for every request:

2026/10/14 08:12:31 [crit] 1184#1184: *42 connect() to unix:/run/php/php8.1-fpm.sock failed
(2: No such file or directory) while connecting to upstream, client: 203.0.113.25,
server: www.example.com, request: "GET /order/ HTTP/2.0",
upstream: "fastcgi://unix:/run/php/php8.1-fpm.sock:", host: "www.example.com"

Running ls /run/php/ shows only php8.3-fpm.sock. The upgrade replaced PHP 8.1 with 8.3, but the site config still names the old socket. The administrator changes fastcgi_pass to unix:/run/php/php8.3-fpm.sock, runs sudo nginx -t, reloads nginx and requests the order page with curl. It returns HTTP/2 200.

A day later, a few 502s appear at lunchtime. This time the log says upstream prematurely closed connection, and the PHP-FPM log shows server reached pm.max_children setting (5). Each PHP process uses about 80 MB and the server has about 2 GB to spare, so pm.max_children is raised to 20. The lunchtime 502s stop.

The fix, step by step

Edge cases worth knowing

• Only some pages fail. Static files are served by nginx directly, so they keep working while anything handled by PHP or the app gives 502. A mix like this points straight at the upstream.
• 502 only on large pages or after login. This often matches the too big header message, caused by large cookies or many Set-Cookie headers. Raise the buffer sizes.
• Intermittent 502 under load. Look for pm.max_children warnings, the out-of-memory killer in sudo dmesg | grep -i kill, or an app that restarts often in pm2 status.
• HTTPS upstreams. If proxy_pass uses https://, a certificate or SNI problem can cause 502s. Add proxy_ssl_server_name on; when the upstream needs the host name.
• Search engines. A short burst of 502s does no lasting harm, but long or repeated outages slow Google's crawling. See Server error (5xx) in Search Console.
• Timeouts that look like 502s. If the log says upstream timed out, you are dealing with a 504. The 504 errors guide covers that.

Keeping 502s away

• Always run sudo nginx -t before reloading, and keep a copy of working configs before upgrades.
• After any PHP or Ubuntu upgrade, run ls /run/php/ and sudo nginx -T | grep fastcgi_pass to check they still agree.
• Make every upstream restart on its own: systemd services with Restart=always, or pm2 with pm2 startup and pm2 save.
• Set up a simple uptime check that requests a PHP or app page, not a static file, every minute.
• Rotate and watch /var/log/nginx/error.log; a sudden rise in connect() failed lines is an early warning.
• Re-crawl the site after changes and look for any 5xx responses. The HTTP error audit guide explains how to read the results.