How to Fix Docker 502 Bad Gateway on Ubuntu 22.04

The Root Cause The “502 Bad Gateway” error on Ubuntu 22.04 with Docker often arises from conflicts between Docker’s network management and the host’s iptables backend (which defaults to nftables on 22.04) or an active UFW firewall. Additionally, this error can indicate that the application inside the Docker container is not running, has crashed, or is not listening on the expected port, preventing the reverse proxy (e.g., Nginx) from successfully connecting.

Quick Fix (CLI)

# Step 1: Ensure iptables is configured for legacy mode.
# Docker traditionally works best with iptables-legacy for network rule management.
sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

# Step 2: Restart the Docker daemon to reapply network rules.
sudo systemctl restart docker

# Step 3: Restart the specific container(s) experiencing the issue.
# Replace <container_name_or_id> with the actual name or ID of your problematic container.
sudo docker restart <container_name_or_id>

# If using Docker Compose, navigate to your project directory and restart the service:
# cd /path/to/your/docker-compose-project
# sudo docker compose restart <service_name>

Configuration Check

Nginx Configuration File: /etc/nginx/sites-available/your_site.conf (or similar, like default) Verify the proxy_pass directive points to the correct Docker container’s exposed port on the host. Ensure it matches the port your Docker container publishes (e.g., 8080).

server {
    listen 80;
    server_name yourdomain.com; # Or your server IP

    location / {
        # Critical: Ensure this matches the exposed port of your Docker container.
        proxy_pass http://localhost:8080;
        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;
    }
}

After editing Nginx configuration, test and reload it:

sudo nginx -t
sudo systemctl reload nginx

Docker Daemon Configuration File (Optional): /etc/docker/daemon.json While generally not needed unless iptables management was explicitly disabled, ensure Docker is configured to manage iptables rules. If this file exists, verify iptables is set to true. Create it if it doesn’t exist and you suspect deeper iptables issues.

{
  "iptables": true
}

If you create or modify daemon.json, restart the Docker daemon:

sudo systemctl restart docker

Verification

# 1. Verify the Docker container is running and healthy.
sudo docker ps -a
# Look for your container. Its STATUS should be 'Up X seconds/minutes' and HEALTHY (if healthchecks are configured).

# 2. Check the container logs for application-specific startup errors or listening messages.
sudo docker logs <container_name_or_id>
# Search for messages confirming your application started successfully and is listening on its port.

# 3. Attempt direct access to the container's exposed port (bypassing Nginx).
# Replace 8080 with your container's exposed port.
curl http://localhost:8080/
# You should receive a successful response from your application.

# 4. Finally, test the service through the reverse proxy (Nginx).
curl http://yourdomain.com/ # Or http://localhost/ if Nginx is on the same host and no domain is configured.
# A successful HTTP response (e.g., 200 OK) indicates the 502 Bad Gateway error is resolved.