If you've ever deployed Traefik and faced 404 errors, missing certificates, or a browser stuck in an endless redirect loop, you're not alone. Fix Traefik common errors is one of the most searched topics in the self-hosting and DevOps community.
With this guide, you can quickly identify exactly what's broken and resolve it under pressure. Whether you're managing containers on a small Linux VPS or a private homelab, these fixes will help you.
How To Fix Traefik Common Errors
When Traefik breaks in production, you often have only a few minutes to find the issue and bring services back online. In this guide, the goal is to fix Traefik common errors clearly so you can move from symptoms to solutions quickly.
Now proceed to the following steps to fix Traefik common error.
Error 1: Traefik ACME Certificates Are Not Issuing
The symptom of ACME certificates not issuing is that your browser shows a self-signed certificate warning. Traefik logs show something like:
HTML/XML
level=error msg="Unable to obtain ACME certificate for domains"
Or the acme.json file is empty after startup.
Here are the root causes and fixes:
Cause 1: Wrong file permissions on acme.json
This is the most common reason. Traefik requires acme.json to have permissions set to exactly 600. If it is 644, 755, or owned by the wrong user, Traefik will refuse to read or write it.
Check current permissions:
Bash
ls-laletsencrypt/acme.json
Fix it with:
Bash
chmod600letsencrypt/acme.json
If you still get a permission denied error after setting 600, the issue might be file ownership. Switch to a named Docker volume instead of a bind mount. This is a known fix that resolves ownership conflicts:
Cause 2: Port 80 is not open or is being redirected before the ACME HTTP challenge completes
Traefik's HTTP challenge requires that port 80 is reachable from the internet. If you redirect all HTTP to HTTPS at the entrypoint level AND use HTTP challenge, the challenge request itself gets redirected and fails:
HTML/XML
# The problem: HTTP challenge traffic hits the redirect, not the challenge handler
To fix it, you can use a DNS challenge instead or use a TLS challenge. DNS challenge is more reliable in most VPS setups:
Let's Encrypt allows 5 failed validation attempts per hour and up to 50 certificate requests per domain per week. If you've been restarting Traefik repeatedly while testing, you may have hit this limit.
To fix it, it is recommended to use the staging server first. Switch to production only when your config is confirmed working:
YAML
1# In traefik.yml - use staging while testing2certificatesResolvers:3letsencrypt:4acme:5caServer:"https://acme-staging-v02.api.letsencrypt.org/directory"6email: you@example.com7storage: /letsencrypt/acme.json8httpChallenge:9entryPoint: web
Once it works with staging, comment out caServer, delete acme.json, and restart Traefik. It will re-issue a production certificate.
Cause 4: The acme.json file is not persisted across restarts
If Traefik is crash-looping and you don't mount acme.json as a persistent volume, it requests a new cert on every restart. You'll hit rate limits quickly.
dockerexectraefikcat/letsencrypt/acme.json# Should contain a JSON object with your cert data, not an empty {}
For full details on every ACME option, challenge type, and rate limit rule, you can check the official Traefik ACME docs.
Error 2: Traefik Routers Return 404
In this situation, Traefik is running, the container is up, but every request returns a plain 404 page not found. The container doesn't show up in the dashboard or API at all.
The root causes and fixes include:
Cause 1: traefik.enable=true is missing
This is the first thing you must check. If you have --providers.docker.exposedbydefault=false set in your static config, then every container must have traefik.enable=true:
Cause 2: Wrong or missing entrypoint on the router
A router bound to the web entrypoint (port 80) will not match traffic arriving on WebSecure (port 443). This causes silent 404s that are easy to miss:
YAML
1# Wrong - router is on 'web' but user browses over HTTPS2labels:3-"traefik.http.routers.myapp.entrypoints=web"4-"traefik.http.routers.myapp.tls=true"# TLS on a non-HTTPS entrypoint = broken56# Correct7labels:8-"traefik.http.routers.myapp.entrypoints=websecure"9-"traefik.http.routers.myapp.rule=Host(`app.example.com`)"10-"traefik.http.routers.myapp.tls=true"
Cause 3: Router name mismatch between router and service
The name used in the router must exactly match the name in services. Even a single hyphen or underscore difference breaks the link:
YAML
1# WRONG - name mismatch2labels:3-"traefik.http.routers.myapp.service=my-app"4-"traefik.http.services.myapp.loadbalancer.server.port=8080"56# CORRECT - names match exactly7labels:8-"traefik.http.routers.myapp.service=myapp"9-"traefik.http.services.myapp.loadbalancer.server.port=8080"
Cause 4: Missing service port definition when container exposes multiple ports
If your container exposes more than one port, Traefik doesn't know which one to forward to. You must define it exactly:
If your router doesn't appear here at all, the problem is a label or provider issue, not a routing rule issue.
Error 3: Docker Label Syntax Errors in Traefik
The symptom of this error is that when you copy a working label example from the internet, paste it into your docker-compose.yml, and Traefik ignores the container entirely, or the router never appears in the dashboard.
Here are the root causes and fixes for this issue:
Cause 1: YAML parsing strips or breaks backticks in rules
The Host() rule in Traefik requires backticks around the domain name. YAML can squish these if you don't quote the whole label value:
YAML
1# BROKEN - YAML may misparse the backtick2labels:3- traefik.http.routers.myapp.rule=Host(`app.example.com`)45# CORRECT - wrap the entire label value in double quotes6labels:7-"traefik.http.routers.myapp.rule=Host(`app.example.com`)"
Cause 2: Using true without quotes in key/value label format
Docker's label parser treats boolean values differently depending on the format you use. When using the YAML key/value (colon) syntax, true must be quoted:
This lets you see exactly what Docker parsed from your YAML, before Traefik even reads it.
Error 4: Container Not Reachable in Traefik
In this case, the router appears in the Traefik dashboard with a green status, but every request returns a 502 Bad Gateway error or times out. The service shows up as unhealthy or with the wrong IP.
Cause 1: Container is on a different Docker network than Traefik
Traefik can only reach containers that share the same Docker network. If your app container is only on the default bridge network and Traefik is on a custom proxy network, they can't communicate.
If the network doesn't exist, you must create it first:
Bash
dockernetworkcreateproxy
Cause 2: Container is on multiple networks
If your container is attached to more than one network, Traefik may pick the first IP in the list, which might be on a network Traefik can't reach. The fix is to pin the network with a label:
YAML
1labels:2-"traefik.docker.network=proxy"
This tells Traefik which network's IP to use when forwarding traffic.
Cause 3: Wrong port in the service label
Always use the internal container port, not the host-mapped port. If your container listens on port 8080 internally but you mapped it to 9090 on the host, use 8080 in the label:
In this situation, your browser shows ERR_TOO_MANY_REDIRECTS. You can see the request bouncing back and forward between HTTP and HTTPS in the network tab.
Cause 1: Service behind Traefik redirects to HTTPS
This is the most common cause. Traefik terminates TLS and forwards traffic to the backend over HTTP. If the backend sees an HTTP request and redirects it to HTTPS, you get an infinite loop.
The backend doesn't know the original request came in over HTTPS because Traefik already handled the TLS part. To fix it, you must tell your backend to trust the X-Forwarded-Proto header.
Cause 2: You applied the redirect middleware to both web and websecure routers
If you add a redirectScheme middleware to a router that's already on the websecure entrypoint, it redirects HTTPS back to HTTPS. To fix it, apply the redirect middleware only to the HTTP web router:
YAML
1labels:2# HTTP router - only redirects to HTTPS3-"traefik.http.routers.myapp-http.entrypoints=web"4-"traefik.http.routers.myapp-http.rule=Host(`app.example.com`)"5-"traefik.http.routers.myapp-http.middlewares=redirect-https"6-"traefik.http.middlewares.redirect-https.redirectscheme.scheme=https"7-"traefik.http.middlewares.redirect-https.redirectscheme.permanent=true"89# HTTPS router - serves actual traffic, no redirect middleware here10-"traefik.http.routers.myapp.entrypoints=websecure"11-"traefik.http.routers.myapp.rule=Host(`app.example.com`)"12-"traefik.http.routers.myapp.tls=true"
Cause 3: Global redirect is enabled and container sets up an HTTP router that redirects
If you use the global entrypoint redirect in traefik.yml, you don't need a redirect middleware on each container. Having both creates a loop.
You must set a global redirect once in traefik.yml:
With this, you must remove any redirect middleware from your container labels. Just define the websecure router.
Cause 4: Traefik is behind another proxy that passes X-Forwarded-Proto: https and Traefik doesn't trust it
If you use a tunnel like Cloudflare Tunnel, Pangolin, or a load balancer in front of Traefik, Traefik needs to be told to trust forwarded headers from internal IPs:
In this issue, your app loads, but real-time features don't work. The browser console shows WebSocket errors like:
HTML/XML
WebSocket connection to 'wss://…' failed
Or mixed content warnings about ws:// on an HTTPS page.
Cause 1: App is connecting using ws:// but the page is served over HTTPS
Browsers block ws:// connections on HTTPS pages. The app itself needs to use wss://. This is usually a frontend config issue, not a Traefik issue.
Cause 2: Missing X-Forwarded-Proto header for WebSocket upgrade
Traefik handles WebSocket connections automatically, and it supports the HTTP Upgrade mechanism without special config. But if the X-Forwarded-Proto header isn't passed, the backend may not know the connection started over HTTPS, and may try to downgrade it.
Most Traefik problems after deployment depend on a few things, including permissions on acme.json, missing labels, network isolation, or redirect conflicts. Keep the Traefik API and dashboard enabled in development, check your labels with docker inspect, and always test with Let's Encrypt staging before going to production. With a stable, well-configured Traefik setup, you can run everything from web apps to API gateways reliably on a single VPS.
Get full root access and run Traefik reliably on a PerLod Linux VPS. Make sure your domain DNS is pointed correctly before running any ACME challenge. You can easily register your domain at PerLod.
Usually, it is a permissions issue or Let's Encrypt rate limit. Check Traefik logs with docker logs traefik for the exact error.
No special config is needed. Traefik handles WebSocket upgrade automatically. You only need to ensure the right headers are passed to the backend.
No. DNS challenge doesn't require port 80 to be reachable from the internet.
We use cookies to run PerLod and to understand how the site is used. You can accept everything, or open Manage to turn individual categories off. Cookie policy.