To troubleshoot a Traefik entry point, follow the path of the request: the certificate comes before HTTP, the 404 happens when the route is chosen, the 502 and the 504 when the backend is reached, and a redirect loop shows in the response headers. Each symptom points to a layer, and each layer has its own signal. This lesson gives the reading order, the logs to enable and the traps that make you fix the wrong layer. It targets Traefik 3.7.15.
What you will learn
The lesson is organized as a method: locate the symptom, read the right signal, then validate the repair with a real response.
- Place a symptom on the layer that produces it.
- Read an access log: router, target service, code and duration.
- Tell a default certificate, a test certificate and a certificate that does not match the requested name apart.
- Explain a redirect loop and measure it with
curl. - Validate a repair with the real response, not with the absence of errors.
Prerequisites
This lesson assumes you already know how to publish a service and read an HTTP code. The basic measurements are in the lessons listed here.
- The path of a request, SNI and the 404, 502 and 504 codes: Publish a web service.
- Traefik's model, its providers and the table of common errors: Traefik.
- Publishing containers and host services: Traefik with Docker and the file provider.
- JSON access logs: Observing Traefik.
Which layer should you start with?
Start with the layer closest to the client, then work your way down. A request goes through DNS, the TCP connection, the TLS negotiation, the route choice, the connection to the backend, then the response. A problem upstream hides everything that follows: as long as the certificate is rejected, no HTTP request reaches the route.
| Observed symptom | Layer involved | First observation |
|---|---|---|
| Certificate warning | TLS, before HTTP | subject and issuer of the certificate presented |
404 page not found | route choice | access log line, associated router |
502 | connection to the backend | target URL of the service in the access log |
504 or very slow response | wait for the backend | duration of the line, configured timeouts |
| Redirects that never end | redirect | chain of Location headers |
A simple rule keeps you from changing things at random: change one thing at a time, then send the same request again. If two failures coexist, the first repair reveals the next one, and that is normal.
Which logs should you enable before diagnosing?
By default, Traefik logs at the ERROR level, and the access log is disabled. A 404 with no route, a 502 or a 504 then leave no trace in the process logs: an empty log does not prove that Traefik saw nothing. Enable the access log before reproducing the failure, as Observing Traefik details.
The JSON format gives named fields. Four are enough for most diagnoses:
RouterName, the router chosen for the request;ServiceURL, the backend actually contacted;DownstreamStatus, the code returned to the client;Duration, the time spent, in nanoseconds.
Read them together. A 404 with no router chosen is about the route. A 502 with an unexpected ServiceURL is about an address or a port. A Duration close to 30 seconds with a 504 is about a backend that does not answer the connection. For errors raised while building objects (badly written rule, missing middleware), the ERROR level is enough: the message names the faulty object.
What does a 404 mean?
A 404 from Traefik means that no active router matches the request. The route may be missing, written differently from the requested name, or disabled by a configuration error. Check the causes in this order.
- Do the name and the entrypoint of the request match the rule and the
entryPointsof the router? - Is the router active? A router that cites a missing service or middleware is disabled, and the error is written at the
ERRORlevel. - Is the cited object written with the right provider suffix (
@file,@docker)? A missing suffix makes Traefik look for the object in the wrong provider. - If the routes come from a file, has the file been reloaded? Since version 3.7.12, a read error mentions the file name.
If Traefik's API is enabled, it lists each router with its status and its possible error; exposing it without protection is a risk, covered in Protecting the Traefik entry point.
What do a 502 and a 504 reveal?
Both codes are about the backend, but not about the same failure. A 502 means that the connection was refused or that the response is invalid. A 504 means that the backend did not answer within the timeout.
The default timeouts explain behaviors that surprise people. In the server transport reference, forwardingTimeouts.dialTimeout is 30s: Traefik then gives up on the connection and returns a 504. On the other hand forwardingTimeouts.responseHeaderTimeout is 0s, that is, no timeout: a backend that accepts the connection and then answers very slowly does not cause a 504 until you set that timeout. A "slow" page is therefore not necessarily a Traefik failure.
To decide between the route, the network and the application, compare these three observations: the target URL in the access log, the backend's response when called from the machine where Traefik runs, and the duration of the line. If the backend answers fine from there but not through Traefik, look for a mismatch of port, network or protocol (HTTP versus HTTPS) in the service definition.
Why does the browser show a certificate warning?
The warning comes from the TLS negotiation, before any HTTP request. Traefik picks the certificate according to the name the client announces (the SNI): inspect what is actually presented for that name.
openssl s_client -connect <host>:443 -servername <requested-name> </dev/null 2>/dev/null \ | openssl x509 -noout -subject -issuer -datesThe command prints the subject, the issuer and the dates of the certificate served for that name. Three readings are possible.
- The subject is
TRAEFIK DEFAULT CERT: no certificate matches the announced name, so Traefik serves its default certificate, which is self-signed. Look for a router without TLS, a name different from the requested one, or a missing certificate. - The issuer is a test or staging authority: the certificate is valid for another chain of trust, which the browser does not accept. That is normal in a lab, and an error in production.
- The subject is right, but the dates have passed: renewal failed. The causes are described in Traefik and automatic HTTPS.
How does a redirect loop come about?
A loop appears when a redirect sends the client to an address that triggers the same redirect. The browser ends up showing an error message with no page. Two situations are the classic source.
- An HTTP-to-HTTPS redirect is attached to a router that also answers over HTTPS: the already encrypted request is sent back to itself.
- Another proxy placed in front of Traefik terminates TLS and talks to it over HTTP: Traefik thinks it receives plain text and redirects to HTTPS, the proxy sends plain text again, and so on.
The redirect can be measured without a browser. curl follows redirects with -L, and --max-redirs limits their number.
curl -sIL --max-redirs 5 http://<requested-name>/If the chain goes in circles, curl stops with the message Maximum (5) redirects followed and you see the same address coming back in the Location headers. The fix is to put the redirect where the request is still in plain text, or to tell Traefik the real scheme when a proxy sits in front. The details of redirecting per entrypoint are in Traefik and automatic HTTPS.
Hands-on: bring an entry point back to a working state
The exercise presents several services that have become unstable, with missing pages, gateway errors, slowness, a certificate warning and an endless redirect. You must locate each failure in the logs and the responses, repair the configuration, then check the result.
Key points
A reliable diagnosis follows the order of the request and relies on one signal per layer.
- The certificate comes before HTTP; the 404 happens when the route is chosen; the 502 and the 504 when the backend is reached.
- Enable the access log before reproducing the failure: the default level does not keep these codes.
TRAEFIK DEFAULT CERTsignals a name without a certificate, not an expired certificate.- Without a configured response timeout, a slow backend does not produce a
504. - A redirect loop is measured with
curl -L --max-redirs. - Change one thing at a time, then send the same request again.
Knowledge check
The quiz checks the reading order of the layers, the error codes and the signals specific to each failure.
Knowledge check
Check what you have learned with this interactive quiz
How it works
- The timer starts when you click Start
- Multiple choice, true/false and short answer questions
- You can move between questions
- Detailed results are shown at the end
Starts the quiz and the timer
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
Continue the course: Upgrade Traefik and roll back: from 3.7.6 to 3.7.15
A new full quiz with random questions
Work again only on the questions you missed