Skip to content

Docker Nginx 502 Bad Gateway Fix

DodaTech Updated 2026-06-24 3 min read

In this tutorial, you'll learn about Docker Nginx 502 Bad Gateway Fix. We cover key concepts, practical examples, and best practices.

A 502 Bad Gateway from Nginx in Docker means Nginx cannot reach the upstream application container. This happens when the application container is down, the port is wrong, the network is misconfigured, or the application binds to localhost instead of 0.0.0.0.

The Problem

curl http://localhost

Returns:

<html>
<head><title>502 Bad Gateway</title></head>

Nginx logs show:

2026/06/24 10:30:00 [error] connect() failed (111: Connection refused) while connecting to upstream

Wrong Approach

# WRONG β€” Nginx on host network, app on bridge with wrong upstream
services:
  nginx:
    image: nginx
    ports:
      - "80:80"
  app:
    image: my-app:latest
    ports:
      - "3000:3000"  # Unnecessary β€” Nginx communicates over internal network

Right Approach

# RIGHT β€” same network, correct upstream
services:
  nginx:
    image: nginx
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - app
  app:
    image: my-app:latest
    expose:
      - "3000"
    environment:
      - HOST=0.0.0.0  # Bind to all interfaces

With Nginx config:

upstream app {
    server app:3000;
}

server {
    listen 80;
    location / {
        proxy_pass http://app;
    }
}

Step-by-Step Fix

Step 1: Check the upstream container is running

docker ps --filter name=app

Step 2: Check the application logs

docker logs app --tail 50

Step 3: Test connectivity from Nginx container

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

If this fails, the network or hostname is wrong.

Step 4: Ensure the application binds to 0.0.0.0

# WRONG β€” binds to localhost only
app.run(host='127.0.0.1', port=3000)

# RIGHT β€” binds to all interfaces
app.run(host='0.0.0.0', port=3000)

Step 5: Check network configuration

docker network ls
docker inspect app --format '{{.NetworkSettings.Networks}}'

Step 6: Verify Nginx config inside container

docker exec nginx nginx -t
docker exec nginx cat /etc/nginx/conf.d/default.conf

Prevention Tips

  • Always bind applications to 0.0.0.0 inside containers
  • Use service names (not IPs) for upstream definitions
  • Place all services on the same Docker network
  • Add healthchecks to upstream services
  • Test with curl from the Nginx container before debugging the browser

Common Mistakes with nginx 502

  1. Using return to exit a function early instead of wrapping a pure value in the monad
  2. Mixing let bindings with <- bindings in do notation, producing type errors
  3. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors

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

### Why does Nginx return 502 when the app container is running?

The app binds to 127.0.0.1 inside the container, which is unreachable from Nginx. Change the bind address to 0.0.0.0. Alternatively, the port in the Nginx upstream directive does not match the port the application listens on.

How do I debug connectivity between Nginx and the app container?

Exec into the Nginx container and use curl or wget to reach the app by service name: docker exec nginx curl http://app:3000. If this fails, check the Docker network and DNS resolution with docker exec nginx getent hosts app.

Should I use the container IP instead of the service name?

No. Service names (DNS) are automatically resolved by Docker's embedded DNS server. Container IPs change on restart. Always use the service name from docker-compose.yml in the Nginx upstream configuration.

← Previous Cum sΔƒ gestionezi reΘ›ele Docker Next β†’ How to Fix Docker Nginx Reverse Proxy 502 Error

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Quick Fix