Skip to content

Troubleshooting

Work from whose answer you are reading. Almost every fault below was met, or deliberately staged, in the lab; the log line in the configuration-refused case is the real one (transcript t07) with only the timestamp kept as it fell.

"404 page not found", in plain text

  • Symptom: Every request to a site returns 404 with the bare body 404 page not found.
  • Meaning: The answer is Traefik's own. No router matched.
  • Check, in order: Is the router in /api/http/routers at all? If not, its file was refused (see below) or the provider never saw it. If it is there, read its rule character by character against the request: host, path, entrypoint. A router defined on websecure never sees traffic that arrives on web.

A 404 in the site's own style instead

  • Meaning: Routing worked. The backend returned the 404.
  • Check: The path the backend received — if a stripPrefix middleware is involved, it received a different path than the visitor sent, by design (chapter 6). Test the backend directly on its own port with that path.

"502 Bad Gateway"

  • Meaning: A router matched; the service could not produce an answer.
  • Check: Is the backend up, at the address the service names? Curl it directly. In Docker setups, is Traefik on a network that can reach the container (chapter 9's networking fact)? If the backend is up and the address is right, look for the health check condemning it (next case).

All servers vanish; the site answers 503

  • Meaning: Every server failed its health check (chapter 10), or the service has no servers at all.
  • Check: The health path itself — curl it on each backend. The classic error is checking a path the backend answers with a redirect or a 401; Traefik counts anything but a 2xx as down, and it is right by its own rule.

I edited the file and nothing changed

  • Meaning: Either the watch is off (watch: true missing in the file provider's static config — chapter 3), or the edit was refused.
  • Check the log for: error while parsing rule Host(broken.test) && PathPrefix(: 1:35: expected ')', found 'EOF' — the message names the router, the rule, and the character position. Fix the syntax; the new file is applied the moment it parses. Until then the last good configuration serves, silently — which is mercy, and also why "nothing changed" is the symptom of a loud error sitting unread in the log.
  • And check the API: if the router shows the old rule in /api/http/routers, Traefik is telling you exactly which configuration it is running. Believe it over your editor.

The browser warns about the certificate

  • "Not trusted" (curl exit 60): The visitor's machine doesn't trust the issuing CA. For a lab CA, that is correct until you install the CA (chapter 7). For a public site, the certificate Traefik presented was not the one you expected — see next case.
  • The certificate names something odd, or is Traefik's built-in default: The configured certificate was not loaded — almost always a path problem: certFile is resolved relative to Traefik's working directory with the file provider. Traefik falls back to its own generated default certificate rather than failing, so HTTPS "works" with a stranger's name on it. Check the log at startup for certificate errors, and use absolute paths when in doubt.

The redirect loops forever

  • Symptom: HTTP redirects to HTTPS, which redirects to HTTPS, endlessly.
  • Meaning: The redirect middleware (or entrypoint redirection) is also attached to the secure router, or the backend is generating the second redirect because it believes — from missing or distrusted forwarding headers — that the request arrived in plain HTTP.
  • Check: Middlewares listed on the websecure router; and what x-forwarded-proto your backend actually receives (the lab backend's echo shows it, which is why the lab backend echoes it).

The middleware is attached but does nothing

  • Meaning: Usually a naming fault. A router in one provider referring to a middleware from another needs the suffix: warden-auth@file. A bare name that resolves to nothing is skipped with an error in the log and a warning in /api/overview.
  • Check: /api/http/middlewares lists what exists; /api/http/routers shows what the router thinks it is carrying. Compare spellings, including the dull possibility of a hyphen.