Introduction to Troubleshooting Traefik Proxy
Traefik is a modern, cloud-native reverse proxy and load balancer that has become a staple in containerized environments. While its dynamic configuration and automatic service discovery make it powerful, these same features can introduce complexity when things go wrong. This tutorial walks you through the most common Traefik issues, how to diagnose them, and how to fix them with confidence.
What Is Traefik Proxy?
Traefik is an open-source edge router that integrates natively with orchestrators like Docker, Kubernetes, and Swarm. Instead of manually reloading configuration files, Traefik listens to your orchestrator's API and automatically updates its routing rules as services are added or removed. This makes it ideal for microservices architectures where infrastructure changes frequently.
Why Troubleshooting Matters
Because Traefik sits at the edge of your infrastructure, every request to your applications passes through it. A misconfigured router, a missing certificate, or a failed health check can take down entire services. Understanding how to diagnose and resolve these issues quickly is essential for maintaining uptime and reliability. The good news is that Traefik provides excellent observability tooling — you just need to know where to look.
Essential Diagnostic Tools
Before diving into specific issues, you should familiarize yourself with Traefik's built-in diagnostic features. These tools form the foundation of every troubleshooting workflow.
The Traefik Dashboard
Traefik ships with a web dashboard that displays all configured routers, services, middlewares, and TLS certificates. Enable it in your static configuration:
entryPoints:
traefik:
address: ":8080"
api:
dashboard: true
insecure: true
Access the dashboard at http://localhost:8080/dashboard/. Note the trailing slash — omitting it will result in a 404. The insecure option is fine for development, but in production you should protect the dashboard with authentication and TLS.
Access Logs
Access logs show every request Traefik processes, including the response status, upstream service, and timing. Enable them with:
accessLog:
filePath: "/var/log/traefik/access.log"
format: json
JSON format is recommended because it is easier to parse with tools like jq. You can then filter for errors:
cat /var/log/traefik/access.log | jq 'select(.status >= 500)'
Log Level Configuration
Traefik supports several log levels: PANIC, FATAL, ERROR, WARN, INFO, and DEBUG. For troubleshooting, set the level to DEBUG:
log:
level: DEBUG
filePath: "/var/log/traefik/traefik.log"
Debug logs reveal detailed information about provider events, router matching, and certificate management. Remember to revert to INFO or WARN in production to avoid excessive log volume.
Common Issue 1: 404 Not Found Errors
The 404 error is the most frequent Traefik problem. It means Traefik received a request but could not match it to any configured router. There are several root causes.
Router Rule Mismatch
The most common cause is a routing rule that does not match the incoming request. Check your router definition:
http:
routers:
my-router:
rule: "Host(`api.example.com`)"
service: my-service
entryPoints:
- web
If a request comes in for www.example.com, it will not match this rule. Verify the Host header matches exactly. Use the dashboard to confirm the router is registered and inspect its rule.
Wrong EntryPoint Configuration
If your router listens on the web entrypoint (port 80) but the request arrives on websecure (port 443), Traefik will return a 404. Ensure the entrypoint list includes the correct ports:
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
http:
routers:
my-router:
rule: "Host(`api.example.com`)"
service: my-service
entryPoints:
- web
- websecure
Provider Not Discovering Services
In Docker environments, Traefik discovers services through container labels. If labels are missing or malformed, no router is created. Verify your container has the correct labels:
labels:
- "traefik.enable=true"
- "traefik.http.routers.my-router.rule=Host(`api.example.com`)"
- "traefik.http.routers.my-router.entrypoints=web"
- "traefik.http.services.my-service.loadbalancer.server.port=8080"
Common mistakes include forgetting traefik.enable=true, misspelling label keys, or specifying a port that the container does not actually expose.
Common Issue 2: 502 Bad Gateway
A 502 error means Traefik matched a router and tried to forward the request to a backend service, but the service was unreachable or returned an invalid response.
Backend Service Not Running
The first check is whether your backend service is actually running and healthy. Use Docker or your orchestrator to verify container status:
docker ps | grep my-service
docker logs my-service
If the container is restarting or has exited, fix the underlying application issue first. Traefik cannot route to a service that does not exist.
Incorrect Service Port
Traefik needs to know which port your service listens on internally. If you specify port 8080 but your application listens on 3000, the connection will fail. Explicitly define the service port:
labels:
- "traefik.http.services.my-service.loadbalancer.server.port=3000"
In file-based configuration, the equivalent is:
http:
services:
my-service:
loadBalancer:
servers:
- url: "http://backend:3000"
Network Connectivity Issues
In Docker Compose setups, Traefik and your backend services must share a network. If they are on different networks, Traefik cannot reach the backend. Define a shared network:
networks:
proxy-net:
driver: bridge
services:
traefik:
image: traefik:v3.0
networks:
- proxy-net
# ...
my-app:
image: my-app:latest
networks:
- proxy-net
# ...
Verify connectivity by exec-ing into the Traefik container and testing the backend:
docker exec -it traefik wget -qO- http://my-app:3000
Common Issue 3: TLS and HTTPS Problems
TLS issues are common and can manifest as browser warnings, redirect loops, or failed certificate provisioning.
Certificate Acquisition Failures
Traefik uses Let's Encrypt (ACME) to automatically provision TLS certificates. If certificate acquisition fails, check the following common causes:
- DNS records do not point to your Traefik instance
- Port 80 is not accessible from the internet (required for HTTP-01 challenge)
- You have hit Let's Encrypt rate limits
- The ACME configuration references a non-existent storage file path
A correct ACME configuration looks like this:
certificatesResolvers:
letsencrypt:
acme:
email: admin@example.com
storage: /etc/traefik/acme.json
httpChallenge:
entryPoint: web
Ensure the acme.json file has secure permissions:
chmod 600 /etc/traefik/acme.json
HTTPS Redirect Loops
A redirect loop occurs when Traefik continuously redirects between HTTP and HTTPS. This typically happens when Traefik sits behind another proxy that terminates TLS but forwards requests as HTTP. Traefik sees HTTP and tries to redirect to HTTPS, creating an infinite loop.
Fix this by trusting the X-Forwarded-Proto header:
entryPoints:
web:
address: ":80"
forwardedHeaders:
trustedIPs:
- "10.0.0.0/8"
- "172.16.0.0/12"
websecure:
address: ":443"
forwardedHeaders:
trustedIPs:
- "10.0.0.0/8"
- "172.16.0.0/12"
Only list the IP ranges of your upstream proxies in trustedIPs. This tells Traefik to respect the forwarded protocol header instead of relying on the actual connection protocol.
Mixed Content and Incomplete TLS Configuration
If your site loads over HTTPS but resources are requested over HTTP, browsers will block them. Ensure all routers that should be secure reference the TLS section and the correct certificate resolver:
http:
routers:
my-router:
rule: "Host(`api.example.com`)"
service: my-service
entryPoints:
- websecure
tls:
certResolver: letsencrypt
Common Issue 4: Middleware Not Working
Middlewares modify requests and responses in Traefik. When they do not work as expected, the issue is usually a naming mismatch or incorrect ordering.
Middleware Reference Errors
Routers reference middlewares by name. If the name does not match an existing middleware definition, Traefik silently ignores it (or returns an error in debug logs). Verify the names match exactly:
http:
routers:
my-router:
rule: "Host(`api.example.com`)"
middlewares:
- auth-middleware
- rate-limit
service: my-service
middlewares:
auth-middleware:
basicAuth:
users:
- "admin:$apr1$xyz$abc123"
rate-limit:
rateLimit:
average: 100
burst: 50
In Docker label format, the same configuration would be:
labels:
- "traefik.http.routers.my-router.middlewares=auth-middleware,rate-limit"
- "traefik.http.middlewares.auth-middleware.basicauth.users=admin:$$apr1$$xyz$$abc123"
- "traefik.http.middlewares.rate-limit.ratelimit.average=100"
- "traefik.http.middlewares.rate-limit.ratelimit.burst=50"
Note the doubled dollar signs in Docker labels — Docker Compose performs variable interpolation, so you must escape $ as $$.
Middleware Ordering
Middleware execution order follows the order listed in the router's middlewares array. This matters when middlewares depend on each other. For example, rate limiting should typically come before authentication to prevent brute-force attacks from consuming auth resources. Always review the order when chaining multiple middlewares.
Common Issue 5: Performance and Timeout Issues
Traefik is generally fast, but misconfigured timeouts or resource limits can cause performance problems.
Request Timeouts
By default, Traefik has no request timeout, which means slow backends can hold connections indefinitely. Configure timeouts using the forwardingTimeouts section:
serversTransport:
forwardingTimeouts:
dialTimeout: "30s"
responseHeaderTimeout: "0s"
idleConnTimeout: "90s"
entryPoints:
web:
address: ":80"
transport:
respondingTimeouts:
readTimeout: "60s"
writeTimeout: "60s"
idleTimeout: "180s"
If your backend services handle long-running requests (like file uploads or streaming), make sure writeTimeout and responseHeaderTimeout are set high enough to accommodate them.
High Memory Usage
Traefik can consume significant memory in high-traffic environments with access logging enabled. If memory usage is high, consider the following optimizations:
- Disable access logging for health check endpoints using filters
- Reduce the log level from DEBUG to INFO or WARN
- Use the JSON log format and ship logs to an external aggregator
- Monitor the number of active connections and adjust worker counts
You can filter access logs to exclude noisy endpoints:
accessLog:
filePath: "/var/log/traefik/access.log"
filters:
statusCodes:
- "200"
- "300"
retryAttempts: true
minDuration: "10ms"
Best Practices for Traefik Reliability
Beyond fixing specific issues, following these best practices will help you avoid problems before they occur.
Use Health Checks
Configure health checks so Traefik only routes to healthy backends. This prevents 502 errors when a service is starting up or has crashed:
http:
services:
my-service:
loadBalancer:
healthCheck:
path: /health
interval: "10s"
timeout: "3s"
servers:
- url: "http://backend:3000"
Pin Traefik Versions
Always use a specific version tag rather than latest. This prevents unexpected behavior changes when a new version is released:
image: traefik:v3.0.4
Separate Static and Dynamic Configuration
Keep your static configuration (entrypoints, providers, log settings) in a separate file from your dynamic configuration (routers, services, middlewares). This makes it easier to manage and debug:
# traefik.yml (static)
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
providers:
file:
directory: "/etc/traefik/dynamic"
watch: true
# /etc/traefik/dynamic/routers.yml (dynamic)
http:
routers:
my-router:
rule: "Host(`api.example.com`)"
service: my-service
Monitor with Metrics
Enable Prometheus metrics to gain visibility into Traefik's performance and catch issues proactively:
metrics:
prometheus:
addEntryPointsLabels: true
addServicesLabels: true
entryPoint: traefik
Then scrape the metrics endpoint at http://localhost:8080/metrics and set up alerts for error rates, latency spikes, and certificate expiration.
Conclusion
Troubleshooting Traefik effectively comes down to understanding its configuration model and leveraging its built-in observability tools. By mastering the dashboard, access logs, and debug logging, you can quickly identify whether a problem lies in routing rules, backend connectivity, TLS configuration, or middleware setup. The issues covered in this tutorial — 404 errors, 502 bad gateways, TLS failures, middleware misconfigurations, and timeout problems — represent the vast majority of Traefik troubleshooting scenarios. By following the best practices of health checks, version pinning, configuration separation, and metrics monitoring, you can build a resilient Traefik deployment that minimizes downtime and handles traffic reliably at scale.