Traefik is an excellent reverse proxy for Docker environments, providing automatic TLS certificates and dynamic routing. However, when something breaks, symptoms can look confusing.
This guide summarizes practical troubleshooting steps based on real-world debugging of a production home-lab setup using Traefik, Docker, and Let’s Encrypt.
Typical Architecture
A common setup looks like:
Internet
↓
DNS → Host IP
↓
Traefik (Docker container)
↓
Application containers
Traefik handles:
- TLS certificates
- Reverse proxy routing
- HTTPS redirect
- Service discovery
Most Common Error Types
1. HTTP 404 from Traefik
Meaning:
Request reached Traefik
but no router matched the request.
Common causes:
- Host rule mismatch
- Wrong domain name
- Missing router configuration
- Missing path prefix rules
Check routers:
curl http://localhost:8080/api/http/routers
Fix:
Ensure router rule matches request:
rule: Host(`app.example.com`)
2. HTTP 502 Bad Gateway
Meaning:
Router matched
but backend service unreachable.
Most common cause: wrong backend IP or port.
Test backend directly:
curl http://localhost:9000 -I
If this works but Traefik gives 502, fix service URL:
Bad:
url: "http://172.x.x.x:9000"
Good:
url: "http://sonarqube:9000"
Use container names instead of IPs.
3. Dashboard returns 404
Dashboard requires routing both paths:
/dashboard
/api
Fix router rule:
rule: Host(`traefik.example.com`) &&
(PathPrefix(`/api`) || PathPrefix(`/dashboard`))
Also ensure trailing slash:
/dashboard/
4. TLS Certificate Not Issued
Check ACME logs:
docker logs traefik | grep -i acme
Verify:
- DNS challenge configured
- Secrets mounted correctly
- acme.json writable
Permissions should be:
chmod 600 acme.json
5. TLS Renewal Concerns
Traefik automatically renews certificates 30 days before expiry.
Check expiry:
echo | openssl s_client \
-servername app.example.com \
-connect app.example.com:443 \
2>/dev/null | openssl x509 -noout -dates
Renewal happens automatically if Traefik stays running.
Debugging Workflow (Recommended)
When something fails, follow this order:
Step 1 — Is Traefik running?
docker ps
Step 2 — Check routers
curl http://localhost:8080/api/http/routers
Step 3 — Check backend
curl http://localhost:<port>
Step 4 — Check logs
docker logs traefik
Step 5 — Test routing locally
curl -k -H "Host: app.example.com" https://localhost -I
Best Practices for Stable Setup
Use container names instead of IPs
Avoid hardcoded LAN IPs.
Keep all services on same Docker network
Example:
networks:
- traefik-public
Remove exposed ports
Let Traefik handle access.
Backup certificates
Cron backup:
0 3 * * * cp /opt/traefik/data/acme.json /backup/
Freeze Docker versions
Avoid surprise upgrades:
sudo apt-mark hold docker-ce docker-ce-cli containerd.io
Quick Diagnosis Cheat Sheet
| Error | Meaning |
|---|---|
| 404 | Router mismatch |
| 502 | Backend unreachable |
| TLS error | Cert or DNS issue |
| Dashboard 404 | Router rule incomplete |
Final Advice
Most Traefik problems are not Traefik itself, but:
- router rules
- backend targets
- entrypoint mismatches
- DNS configuration
Once routing and networks are correct, Traefik runs reliably for years.
Conclusion
Traefik simplifies TLS and routing, but clear troubleshooting patterns save hours when issues arise. Use this guide as a reference whenever routing or certificates behave unexpectedly.
Add to favorites
