How to Fix Docker Nginx Reverse Proxy 502 Error

In this tutorial, you'll learn about How to Fix Docker Nginx Reverse Proxy 502 Error. We cover key concepts, practical examples, and best practices.

Your Nginx reverse proxy running in Docker returns 502 Bad Gateway — Nginx cannot reach the upstream application container due to wrong hostname, port, or networking.

The Problem

2026/06/24 10:00:00 [error] 1#1: *1 connect() failed (111: Connection refused)
while connecting to upstream, client: 172.17.0.1, server: example.com,
upstream: "http://app:3000"

Browser shows:

502 Bad Gateway
nginx/1.25.0

Step-by-Step Fix

Step 1: Check upstream container is running

docker ps | grep app

If not running, start it:

docker compose up -d app

Step 2: Verify upstream container health

docker logs app

Check if the application is listening on the expected port inside the container.

Step 3: Test connectivity from Nginx container

docker exec nginx curl -v http://app:3000

If this fails, the service name or port is wrong.

Step 4: Fix the Nginx configuration

# WRONG — wrong hostname or port
proxy_pass http://localhost:3000;

# RIGHT — use container/service DNS name
proxy_pass http://app:3000;

Nginx cannot use localhost to reach another container — use the container name or service name.

Step 5: Ensure both containers are on the same network

docker network ls
docker network inspect <network> | grep -E "app|nginx"

If they are on different networks, connect them:

docker network connect <shared-network> nginx
docker network connect <shared-network> app

Step 6: Use docker-compose with a shared network

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    networks:
      - app-network

  app:
    image: myapp:latest
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Step 7: Check if the app binds to 0.0.0.0 inside the container

The app inside the container must listen on 0.0.0.0 not 127.0.0.1:

# WRONG
app.listen(3000, '127.0.0.1');

# RIGHT
app.listen(3000, '0.0.0.0');

Prevention Tips

• Put Nginx and the app on the same Docker network
• Use container names (not localhost) in proxy_pass
• Test connectivity with docker exec
• Ensure apps listen on 0.0.0.0 inside containers
• Use healthchecks to verify upstream readiness

Common Mistakes with nginx proxy

1. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
2. Using head and tail instead of pattern matching, causing runtime errors on empty lists
3. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks

These mistakes appear frequently in real-world DOCKER code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ