How to Fix Traefik 502 Bad Gateway in Docker Compose & Coolify
Resolve Traefik 502 Bad Gateway errors in Docker Compose and Coolify. Fix loadbalancer.server.port mismatches, 127.0.0.1 localhost binding traps, and isolated Docker bridge networks.
A 502 Bad Gateway error from Traefik means Traefik matched the incoming Host header rule to your router, but failed to establish a TCP connection to the upstream container IP. In 95% of Docker Compose and Coolify deployments, this is caused by one of three misconfigurations: (1) your application binds to 127.0.0.1 (loopback) instead of 0.0.0.0 inside the container, (2) your container Dockerfile exposes multiple ports (or no EXPOSE directive) and traefik.http.services.<name>.loadbalancer.server.port is missing or points to the host port instead of the internal container port, or (3) Traefik and your container sit on different Docker networks without an explicit traefik.docker.network label.
Verified Root Causes in Production Environments
- Loopback Binding Inside Container (127.0.0.1 vs 0.0.0.0): Frameworks like Next.js, Vite, Fastify, and Flask bind to 127.0.0.1 by default in certain modes. Because Traefik runs in a separate container with its own network namespace, connecting to the app container's bridge IP (172.18.0.x) fails with ECONNREFUSED.
- Host Port vs Container Port Confusion in Labels: Setting loadbalancer.server.port=8080 when your compose file maps 8080:3000. Traefik routes directly over the internal Docker virtual ethernet bridge, bypassing host port mappings entirely.
- Multi-Network Routing Ambiguity: When a container attaches to both a backend database network and the proxy network, Traefik may randomly pick the internal database network IP that it cannot reach.
1. Verify Upstream Reachability From Inside the Traefik Container
Before editing labels, verify what IP address and port Traefik has discovered for your upstream service, and test connectivity directly from inside the Traefik network namespace. When Traefik logs readfrom tcp 172.18.0.2:48122->172.18.0.5:3000: connection refused or i/o timeout, the exact error tells you which layer failed.
Connection Refused (RST packet) proves that Traefik reached the container on the shared Docker network, but nothing is listening on that TCP port on the 0.0.0.0 interface. An I/O Timeout proves that Traefik is trying to route to an IP on an isolated Docker bridge network that the Traefik container is not attached to.
# 1. Inspect the IP address and networks assigned to your app container
docker inspect <app_container_name> --format '{{json .NetworkSettings.Networks}}' | jq .
# 2. Test TCP connectivity from INSIDE the Traefik proxy container to the app container
# (In Coolify, the proxy container is named 'coolify-proxy')
docker exec -it coolify-proxy wget -qO- http://<app_container_name>:3000/ || echo "Connection failed"
# 3. Check what interface and port your process is actually bound to inside the app container
docker exec -it <app_container_name> sh -c "ss -tlnp || netstat -tlnp"2. Force 0.0.0.0 Hostname Binding in Next.js, Node.js, and Python
If ss -tlnp inside your container shows 127.0.0.1:3000 instead of 0.0.0.0:3000 or :::3000, your application is only accepting connections originating from inside its own container namespace. In Next.js 14+ standalone mode, passing -H 0.0.0.0 or setting the environment variable HOSTNAME="0.0.0.0" is mandatory.
Similarly, if you are running Fastify, explicitly pass host: '0.0.0.0' to fastify.listen({ port: 3000, host: '0.0.0.0' }), and for Uvicorn/FastAPI pass --host 0.0.0.0. Without this, Traefik's TCP SYN packets to the container's eth0 interface (172.x.x.x) are immediately rejected by the Linux kernel.
# Next.js 14/15 Standalone Dockerfile Fix for Traefik 502
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
# CRITICAL: Force Next.js standalone server.js to bind to all container interfaces
ENV HOSTNAME="0.0.0.0"
ENV PORT=3000
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]3. Explicitly Declare loadbalancer.server.port and traefik.docker.network
When your docker-compose.yml defines both an internal database network (for PostgreSQL/Redis) and an external proxy network (such as traefik-public or coolify), Docker attaches two virtual NICs to your application container. By default, Traefik inspects the container metadata and may select the IP address belonging to the internal database network—resulting in a 30-second hang followed by a 502 Bad Gateway timeout.
Always declare both traefik.docker.network (matching the exact external Docker network name) and traefik.http.services.<service>.loadbalancer.server.port (matching the internal container port, never the host port) in your labels block.
services:
api-server:
build: .
restart: unless-stopped
environment:
- HOSTNAME=0.0.0.0
- PORT=3000
networks:
- internal-db
- coolify
labels:
- "traefik.enable=true"
# Force Traefik to route via the shared proxy network, NOT internal-db
- "traefik.docker.network=coolify"
- "traefik.http.routers.api-prod.rule=Host(`api.vexlo.cloud`)"
- "traefik.http.routers.api-prod.entrypoints=https"
- "traefik.http.routers.api-prod.tls=true"
- "traefik.http.routers.api-prod.tls.certresolver=letsencrypt"
# Always specify the INTERNAL container port (3000), no host ports: mapping needed
- "traefik.http.services.api-prod.loadbalancer.server.port=3000"
networks:
internal-db:
driver: bridge
coolify:
external: truePre-Deployment Verification Checklist
- Verify HOSTNAME=0.0.0.0 is set in container environment variables so the server does not bind to 127.0.0.1.
- Set traefik.http.services.<name>.loadbalancer.server.port to the internal container listening port.
- Add traefik.docker.network=<proxy_network_name> whenever a container connects to more than one Docker network.
- Remove conflicting host ports: mappings (e.g., 3000:3000) when Traefik already proxies traffic over the internal bridge.
Deploy on Vexlo Cloud in 60s (₹149/mo UPI)
Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.
Frequently Asked Questions
Why does my app work on localhost:3000 via SSH tunnel but return 502 Bad Gateway through Traefik?
Because your app is bound to 127.0.0.1 or you mapped host port 3000 to container port 8080 while telling Traefik to connect to port 3000. Traefik connects container-to-container over Docker's internal bridge IP (172.18.x.x) using the internal container port.
How do I fix a Coolify 502 Bad Gateway error after deploying a Docker Compose stack?
In Coolify, ensure the Port Exposes field in the dashboard matches your container's internal listening port, bind your server to 0.0.0.0, and remove any manual host ports: bindings from your compose file.
Why does Traefik randomly return 502 Bad Gateway after restarting Docker Compose?
When a container belongs to multiple Docker networks (e.g., default and proxy), Traefik randomly selects one network IP on restart. Add the label traefik.docker.network=proxy so Traefik always selects the reachable network.