One of the most common and confusing errors you can encounter when managing a web server is the 502 Bad Gateway. If you’re using Nginx, this error page often appears abruptly, completely blocking access to your application. This guide will walk you through exactly what this error means, its root causes, and how to reliably fix it.

The Error

When you try to visit your website, the browser displays a plain white screen with bold black text that reads:

502 Bad Gateway
nginx/1.24.0

Under the hood, if you inspect the Nginx error log located at /var/log/nginx/error.log, you’ll typically find a message like:

2026/02/27 10:15:30 [error] 12345#0: *6789 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.1.10, server: example.com, request: "GET / HTTP/1.1", upstream: "fastcgi://127.0.0.1:9000"

Root Cause

Unlike a 404 error (Page Not Found), a 502 error indicates a problem with server-to-server communication. Nginx is functioning as a reverse proxy. It took your browser’s request, passed it to a backend application server (referred to as the “upstream”), and that upstream server either didn’t respond or returned an invalid response.

The most frequent culprits include:

  1. The Backend Service is Down: The upstream application (e.g., PHP-FPM, a Node.js process, Python Gunicorn, or a Docker container) has crashed or isn’t running.
  2. Incorrect Socket or Port Configuration: Nginx is trying to send traffic to a specific port (like 127.0.0.1:9000) or a Unix socket (like /var/run/php/php8.1-fpm.sock), but the backend application is listening somewhere else.
  3. Application Timeouts: The backend application took too long to process the request (e.g., a massive database query), exceeding Nginx’s predefined timeout limit.
  4. Firewall Blocks: A local firewall like ufw or iptables is blocking the port Nginx uses to talk to the backend.
  5. Permission Issues: Nginx doesn’t have the necessary file system permissions to read and write to the backend Unix socket file.

Step-by-Step Solution

Step 1: Check the Nginx Error Log

The absolute best way to solve a 502 error is to ask Nginx exactly what went wrong. Run this command:

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

You will likely see one of two things:

  • “Connection refused”: The backend is down or listening on the wrong port.
  • “Upstream timed out”: The backend is running but took too long to answer.

Step 2: Verify the Upstream Backend Service

If the error is “Connection refused”, your target application is likely dead. Determine what backend Nginx is trying to reach (Node.js, PHP, Python) and check its status.

For PHP-FPM:

sudo systemctl status php8.1-fpm

(Replace 8.1 with your installed version).

If it says inactive (dead) or failed, start it:

sudo systemctl restart php8.1-fpm

Step 3: Check Server Block Configurations

If the backend service is actively running but you still get a 502, Nginx is pointing to the wrong place.

Open your Nginx configuration file for the site (usually in /etc/nginx/sites-available/your_domain or /etc/nginx/conf.d/default.conf) and locate the location block handling the backend:

location ~ \.php$ {
    fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
    ...
}

Or for proxy configurations:

location / {
    proxy_pass http://127.0.0.1:3000;
}

Crucial Check: Guarantee that the path or port specified actually matches your backend. For PHP, verify the socket exists:

ls -la /var/run/php/php8.1-fpm.sock

If your PHP pool is configured to listen on TCP 127.0.0.1:9000, change fastcgi_pass in Nginx to match that exactly.

Step 4: Fix Socket File Permissions

If you use Unix sockets, Nginx needs permission to read them. By default, Nginx runs as www-data (on Debian/Ubuntu) or nginx (on CentOS/RHEL).

If ls -la shows the socket is owned by root:root with restricted permissions, Nginx will be denied access, throwing a 502. Ensure your backend pool configuration (e.g., /etc/php/8.1/fpm/pool.d/www.conf) has the correct user and group settings:

listen.owner = www-data
listen.group = www-data
listen.mode = 0660

Step 5: Increase Server Timeouts

If your error log showed “Upstream timed out” during a long-running process (like a large file upload or complex database export), you need to give Nginx more patience.

Add these directives inside your location block:

For HTTP Proxies (Node.js, Python, Java):

proxy_read_timeout 300s;
proxy_connect_timeout 75s;

For PHP-FPM (FastCGI):

fastcgi_read_timeout 300s;

Reload Nginx to apply the changes:

sudo nginx -s reload

Prevention

To prevent 502 errors from blinding your users:

  • Set Up Service Auto-Restart: Ensure your backend services (like Node.js apps under PM2, or systemd services) are configured to automatically restart if they crash.
  • Implement Health Checks: Use tools like Monit or external services like Pingdom to monitor your raw backend port directly, not just Nginx.
  • Optimize Slow Queries: If timeouts cause your 502s, increasing the limit is a band-aid. Optimize your database queries and application logic so nothing takes 5 minutes to load in the browser.

Summary

  • A 502 Bad Gateway in Nginx means the reverse proxy failed to retrieve a valid response from the backend application (upstream).
  • It is almost never a problem with Nginx itself, but rather that the backend process is crashed, misconfigured, or timing out.
  • The fastest way to diagnose it is by checking /var/log/nginx/error.log.
  • Fix it by verifying the backend is running, ensuring the port or socket path in proxy_pass perfectly matches reality, and adjusting permissions or timeout limits if necessary.