Traefik troubleshooting

404 — router not found

No router matches the request Host/Path. Check curl -s http://localhost:8080/api/http/routers | jq or the dashboard. On Docker: confirm traefik.enable=true and correct Host() rule. Check entrypoint mismatch (web vs websecure). On Kubernetes: verify IngressRoute namespace, entrypoints, and that Traefik watches that namespace.

502 / 503 Bad Gateway

Router exists but backend is unreachable. Verify loadbalancer.server.port matches the container's exposed port (not the host-mapped port). Test backend directly on the Docker/K8s network. Check Traefik logs for "connection refused" or timeout.

TLS / Let's Encrypt certificate fails

ACME HTTP challenge needs port 80 reachable from the internet and routed through the web entrypoint. Check acme.json permissions (600). Read Traefik logs for ACME errors. DNS must resolve publicly. See the SSL lab for openssl verification.

Docker container not discovered

Traefik must access the Docker socket (or Swarm mode configured). Container needs traefik.enable=true — default is ignore unless exposedByDefault=true. Ensure container and Traefik share a Docker network Traefik can route to.

Another common cause is labels applied to wrong container in compose (service vs container confusion).

Wrong backend or redirect loop

Conflicting routers on the same Host rule — only one wins. Middleware redirect loops: trace with curl -vIL https://example.com. Check HTTPS redirect middleware is not bouncing between entrypoints.

In Traefik, redirect loops are often caused by:

X-Forwarded-Proto misinterpretation
forced HTTPS middleware combined with already-HTTPS upstream
incorrect entryPoint redirects (web → websecure loops)

Address already in use

Another service holds :80 or :443. Find it: ss -tlnp | grep ':443 '. Common conflict with host nginx or a second Traefik instance.

Kubernetes IngressRoute issues

kubectl describe ingressroute myroute -n myns
kubectl logs -n traefik -l app.kubernetes.io/name=traefik
kubectl get endpoints -n myns

Verify the Service has ready endpoints, IngressRoute references the correct Service name/port, and Traefik has RBAC to watch resources in that namespace.

Look out for wrong entryPoints name (web vs websecure mismatch).

Dashboard/API unreachable

Enable in static config and bind carefully (not public without auth):

api:
  dashboard: true
  insecure: true   # dev only — use TLS + auth in production

Other common causes:

dashboard bound only to localhost or internal network
entryPoint mismatch (dashboard exposed on wrong port)

Debugging workflow

1. List active routers and services

curl -s http://127.0.0.1:8080/api/http/routers | jq '.[].name'
curl -s http://127.0.0.1:8080/api/http/services | jq

2. Inspect middlewares

curl -s http://127.0.0.1:8080/api/http/middlewares | jq

Many routing issues are actually middleware-related — basic auth, redirects, stripPrefix, rate limits, or headers middleware changing the request before it reaches the service. Match middleware names on the router to this list.

3. Test with explicit Host header

curl -v -H "Host: api.example.com" http://127.0.0.1/path

4. Check Traefik logs during request

docker logs traefik -f
# or: journalctl -u traefik -f

Practice scenarios

Hands-on Traefik scenarios on live Linux VMs: traefik

Cheatsheet →