Hi Friends! What if your site suddenly shows a “502 Bad Gateway error” while Nginx is running? This usually means:

“Nginx not able to reach the backend service.“

This guide fixes the issue and explains why it happens. No unnecessary theory.

Quick Fix: 502 Bad Gateway error in Nginx Reverse Proxy(Non-Docker Setup)

Use this section for a backend that runs directly on a VM or bare metal server.

Step 1: Check if the Backend is Reachable

In our case, the backed application is running locally on port 3000.

# curl http://127.0.0.1:3000

• ❌ If it fails → backend/application is down or wrong application port number.
• ✅ If it works → Then follow the next steps

Step 2: Check Nginx Error Logs

# tail -f /var/log/nginx/error.log

Common errors you can see in nginx logs:

connect() failed (111: Unknown error) while connecting to upstream

 (111: Connection refused) while connecting to upstream

The above errors confirm that there is a backend connectivity issue.

Step 3: Verify proxy_pass in Nginx config files

Your nginx config files should have the correct backend host and port.

proxy_pass http://127.0.0.1:3000;

Confirm the configuration below:

• You are using the correct port number.
• Backend services are up and running.
• curl command test succeeds with 200 status code.

Step 4: Reload the Nginx service

Any changes made to the nginx config files need a reload or restart of the service.

# nginx -t && systemctl reload nginx

The command “nginx -t” verifies the syntax of the nginx configuration files.

Step 5: Verify

# curl -I http://domain-name (OR) # curl -I http://127.0.0.1

If you see the output as below, Congrats, you have fix the 502 bad gateway error.

HTTP/1.1 200 OK

Quick Fix: 502 Bad Gateway error in Nginx with Docker

Use this section if your backend application and nginx run inside Docker containers.

Step 1: Confirm Backend Container Is Running

# docker ps

• ❌ Exited / Restarting status of container → Then fix the container first.
• ✅ Status Running → note the container name

The Output below for the “docker ps”, where you can find the container name.

CONTAINER ID   IMAGE                COMMAND                  CREATED              STATUS              PORTS                                       NAMES
b56bd32d885c   nginx                "/docker-entrypoint.…"   About a minute ago   Up About a minute   0.0.0.0:9000->80/tcp, :::9000->80/tcp       nginx-container
db61b6f3ba8f   python:3.10-alpine   "sh -c 'python3 -m h…"   10 minutes ago       Up 10 minutes       0.0.0.0:3000->3000/tcp, :::3000->3000/tcp   nginx-app

Step 2: Check Nginx Container Logs

# docker logs nginx-container

We have set up nginx in the Docker container named “nginx-container”. In your case, it can be different; check using the “docker ps” command.

Common Docker-related 502 errors:

 connect() failed (111: Connection refused) while connecting to upstream

“111: Connection refused” is due to an incorrect upstream host (container name) or the host port number.

connect() failed (113: No route to host) while connecting to upstream

“113: No route to host” is a network issue; both containers are in different networks.

Step 3: Fix proxy_pass (Most Common Docker Mistake)

Inside a container, localhost refers to the Nginx container itself, not the backend application.

❌ Wrong Configuration in Nginx file:

proxy_pass http://localhost:3000;

✅ Correct Configuration in Nginx file:

proxy_pass http://app-container:3000;

Where app-container is the backend container name.

Step 3.1: Verify Docker Network

Both containers must share at least one common network. By using the command below, you can check the network for the containers.

# docker inspect <NGINX-CONTAINER-NAME> --format '{{range $k, $v := .NetworkSettings.Networks}}{{$k}}{{end}}'
# docker inspect <APPLICATION-CONTAINER-NAME> --format '{{range $k, $v := .NetworkSettings.Networks}}{{$k}}{{end}}'

If you found that both containers are using a different network, then attach the Nginx network to the application container.

# docker network connect <NGINX-NETWORK> <APPLICATION-CONTAINER>

The best you can do is create both containers on the same network.

Step 4: Reload Nginx

# docker exec nginx-container nginx -t
# docker exec nginx-container nginx -s reload

Step 5: Verify

# curl -I http://localhost:9000

This “localhost:9000” is the Nginx container hosted on port 9000, and this can be different in your case.

Check Nginx Error Logs (Before Restarting Anything)

Even if the quick fix works, always confirm the root cause using nginx error logs.

# tail -f /var/log/nginx/error.log

Most common 502 error patterns:

→ Backend is not running or on the wrong port.

connect() failed (111: Connection refused)

connect() failed (111: Unknown error)

→ Docker containers are on a different network.

connect() failed (113: No route to host)

Logs will tell you the real reason. Always analyze the logs before restarting the services or server

Why does 502 Bad Gateway happen in Nginx?

Nginx acts as a reverse proxy. It receives the client request and forwards it to an upstream service (your backend application).

If Nginx:

• Can’t establish a TCP connection
• Connects but receives no valid HTTP response
• Fails to resolve the upstream host
• Can’t route to the container network

It returns:

502 Bad Gateway

An important part is that 502 doesn’t mean the Nginx services are crashed. It means the upstream service(backend applications) failed.

Production Environment Causes of 502 Bad Gateway Error

This section has the most frequent production causes:

1. Backend or application services are not running

→ The application crashed or did not start properly.

2. Wrong port in proxy_pass configuration.

→ App runs on 3000, and nginx config points to 3001 port.

3. Docker localhost mistake

→ Inside a container, localhost refers to the nginx container in it. Always use the container name of the application in Docker and kubernetes Setup.

4. Containers on different networks

→ Docker DNS works only inside shared networks. Create the containers on the same network, or both networks should be attached.

5. Firewall blocking the upstream port

→ Traffic dropped before reaching the backend, because the port has been blocked in the firewall or the Servers.

When This Is NOT a 502 Problem

If the logs show the below error:

upstream timed out (110: Unknown error)

upstream timed out while reading response header

This usually results in a 504 Gateway timeout, not a 502 Bad Gateway error. This is a different issue and requires different fixes.

Common Mistakes That Make 502 Worse

Please avoid these during an incident:

• Restart the whole server or the nginx service immediately.
• Increasing timeout values without checking logs.
• Editing the config inside the container shell without mounting to your local.
• Ignoring Docker network isolation
• Clear the nginx or system logs before investigating the root cause.

TL;DR

Error: 502 Bad Gateway
Meaning: Nginx cannot establish a valid connection to the upstream backend
Check:
  1. Backend service is running and listening
  2. proxy_pass host and port are correct
  3. Docker containers share at least one network
  4. /var/log/nginx/error.log for 111 or 113 errors
Fix:
  Correct upstream configuration → nginx -t && nginx -s reload

Production Tips

Always test upstream connectivity before touching Nginx configurations.
# curl -I http://<backend-host>:<backend-port> 
If the curl command fails, restarting Nginx will not fix the problem. Fix the backend or networking first

Found This Useful?

If this helped you resolve a 502 error in production, consider bookmarking it for future incidents.

Nginx upstream errors are often simple once you find the exact failure point; then logs always tell the story.