Traefik internal server error with an HTTPS backend (self-signed certificate)
Traefik sends 500, not 502, when it cannot verify a backend's certificate. Tested on 3.7.17: serverName, rootCAs, insecureSkipVerify, Docker labels.
Key points
- A 500 Internal Server Error from Traefik in front of an
https://backend usually means Traefik could not verify the backend's certificate. Traefik maps errors that are not network errors to 500, and a failed certificate check is not one, so you get 500 rather than the 502 that a refused connection gives. cannot validate certificate for 172.18.0.5 because it doesn't contain any IP SANsmeans Traefik connected by IP address (the Docker provider always does) and the certificate names only hostnames. SetserverNameon a serversTransport to a name the certificate does list. That one setting is both the SNI and the name Traefik checks, so verification stays on.certificate signed by unknown authoritymeans the certificate does not chain to a CA Traefik trusts. Put your private CA, or the self-signed certificate itself, inrootCAs. That list replaces the public CAs for that transport. A self-signed backend normally needs bothserverNameandrootCAs.- Docker labels can use a serversTransport but cannot define one. Define it in a file provider and reference it as
name@file. Without@file, Traefik 3.7.17 looked forname@docker, loggedservers transport not found, and the route returned 404. - Since v3.3.5 and v2.11.22 (31 March 2025), certificate errors are logged at ERROR, which shows by default. Older releases log them only at DEBUG, so a 500 with an empty log is normal there.
insecureSkipVerifyalso makes the 500 go away, but it turns off the check entirely. Use it last.
Traefik returns 500 Internal Server Error for an https:// backend when it cannot verify the backend's certificate. The log line names the reason. doesn't contain any IP SANs means Traefik dialed an IP address and the certificate lists only hostnames. certificate signed by unknown authority means the certificate is self-signed or comes from a private CA. The fix that keeps verification on is a serversTransport with serverName set to a name in the certificate, plus rootCAs when the CA is your own:
# dynamic configuration, file provider
http:
serversTransports:
app-tls:
serverName: app.internal # a DNS name the backend's certificate lists
rootCAs:
- /etc/traefik/certs/app-ca.pem # your private CA, or the self-signed cert itselfThen point the service at it. With Docker labels that is traefik.http.services.app.loadbalancer.serverstransport=app-tls@file. insecureSkipVerify: true also makes the 500 go away, because it switches the check off. It belongs at the bottom of the list, not the top.
Here is what Traefik 3.7.17 logged for each case, and the fix for each one. Your addresses and names will differ:
Log line after 500 Internal Server Error error= | What it means | Fix |
|---|---|---|
tls: failed to verify certificate: x509: cannot validate certificate for 172.18.0.5 because it doesn't contain any IP SANs | Traefik checked the IP it dialed; the certificate has no IP in it | serverName set to a DNS name the certificate lists |
... x509: certificate is valid for app.internal, not app | Traefik checked the hostname in the URL, such as a Compose service name | serverName: app.internal |
... x509: certificate signed by unknown authority | The certificate does not chain to a trusted CA | rootCAs with your CA, or the self-signed certificate |
... x509: certificate relies on legacy Common Name field, use SANs instead | The certificate has a name only in its Common Name | Reissue it with a SAN; no Traefik setting fixes this except insecureSkipVerify |
tls: first record does not look like a TLS handshake | The backend port speaks plain HTTP | Use http://, or drop scheme=https from the labels |
servers transport not found app-tls@docker, and the route gives 404 | A label referenced a transport without @file | Add @file to the label |
What the error means: certificates, SANs and the name Traefik checks#
When Traefik forwards a request to an https:// URL, it acts as a TLS client. It opens a TLS connection and checks the certificate the backend presents, the same way a browser does. Two checks have to pass.
The first is the name check. A certificate lists the names it is valid for in its Subject Alternative Name (SAN) field. A SAN entry is either a DNS name, such as app.internal, or an IP address. An IP SAN is an IP address written into the certificate. Traefik checks the host part of the server URL against that list. Suppose the URL holds an IP and the certificate has no IP SANs. Go's verifier then prints the exact sentence people search for: x509: cannot validate certificate for <ip> because it doesn't contain any IP SANs. The text is a fixed string in Go's crypto/x509, and Traefik is written in Go.
The second is the chain check. The certificate must be signed by a certificate authority (CA) that Traefik trusts, directly or through intermediates. A self-signed certificate signs itself, so no trusted CA vouches for it. A private CA is one you run yourself, so it is not in the public list either. Both fail with x509: certificate signed by unknown authority.
Go checks the name before the chain. Its Verify function calls VerifyHostname first and builds the chain afterwards. So a self-signed certificate reached by IP first shows the IP SANs error. Fix the name, and the same backend then shows the unknown authority error. That is not a new problem. It is the second check, which never got a chance to run.
The Docker provider makes the IP case the normal one. It builds each server URL from the container's IP on the shared network, so the host part is always an address such as 172.18.0.5. Almost no self-signed certificate lists a container IP. Even one that did would break when the container got a new address. That is why Docker users hit the IP SANs line far more than anyone else.
Why 500 and not 502#
Traefik picks the status for a failed proxy request in one function, ComputeStatusCode in pkg/proxy/httputil/proxy.go. The logic, on master:
- If the error is an end of file (
io.EOF), send 502. - If the request was canceled, send 499.
- If the error is a Go net.Error (a network error), send 504 if it was a timeout, else 502.
- Anything else gets 500.
A failed certificate check is not a net.Error. Go wraps it as a tls.CertificateVerificationError, so it falls through to the last line. v2.11.0 had the same mapping, written inline in pkg/server/service/proxy.go. In the lab, a connection to a closed port on the same backend got 502 (dial tcp ...: connect: connection refused), while a certificate failure got 500. The body was the 21 bytes Internal Server Error.
That 500 misleads people. It reads like the application crashed, so the search starts in the app's logs. The app never saw the request. Other proxies report the same failure as 502: nginx does, as nginx SSL handshaking to upstream errors shows, and so does Caddy, per Caddy reverse_proxy 502 errors. The usual reading of status codes in 502 vs 503 vs 504 does not cover this case. From Traefik, a 500 with an https:// backend means "check the certificate" before it means "check the app".
Why the log may show nothing#
On current releases, the error is easy to see. Since v3.3.5 and v2.11.22, both released on 31 March 2025, Traefik logs certificate errors at ERROR. The changelog entry is "Error level log for configuration-related TLS errors with backends" (PR 11611). The code calls it isTLSConfigError. It matches two error types: tls.CertificateVerificationError, and tls.RecordHeaderError, which is what plain HTTP on a TLS port produces. Every other proxy error, refused connections included, still logs at DEBUG. With no --log.level set, Traefik 3.7.17 printed:
ERR 500 Internal Server Error error="tls: failed to verify certificate: x509: cannot validate certificate for 10.201.10.2 because it doesn't contain any IP SANs"Before those releases, the same line was DEBUG only. Traefik 3.3.4 and 2.11.21 printed nothing at the default level and returned the 500 silently. With --log.level=DEBUG they showed:
# Traefik 3.3.4
DBG github.com/traefik/traefik/v3/pkg/proxy/httputil/proxy.go:115 > 500 Internal Server Error error="tls: failed to verify certificate: x509: ..."
# Traefik 2.11.21
level=debug msg="'500 Internal Server Error' caused by: tls: failed to verify certificate: x509: ..."So on an older release, a 500 with an empty log is expected. Turn on debug logging. The access log helps too: on 3.7.17 it recorded the 500, the 21-byte body and the backend URL, such as "GET /ip-ca HTTP/1.1" 500 21 ... "https://10.201.10.2:8443" 2ms.
How the cases were reproduced#
Everything on this page was observed on 19 November 2026 unless it is credited to source code or documentation. The proxy was the traefik:v3.7 image, which reported version 3.7.17, built with Go 1.27.3. Traefik 3.3.4 and 2.11.21 ran for the log comparison. The backend was a small Python HTTPS server on one Docker network. It had four certificates. One was signed by a lab private CA for app.internal. Two were self-signed with a SAN, one of them with the CA flag off. The last had a Common Name and no SAN at all. Traefik used the file provider, and for the label cases the Docker provider too. The client was BusyBox wget. No browser, Kubernetes cluster or public CA certificate was part of the test, except one route to www.google.com used to check what rootCAs does to public CAs.
Fix 1: serverName, which fixes the name without switching anything off#
The Traefik reference says serverName "Configures the server name that will be used as the SNI." SNI (Server Name Indication) is the name a TLS client sends at the start of the handshake, so a server can pick the right certificate. The reference stops there. The code goes further. In transport.go, Traefik copies the value into Go's tls.Config as ServerName. Go's own documentation for that field says it "is used to verify the hostname on the returned certificates unless InsecureSkipVerify is given. It is also included in the client's handshake to support virtual hosting unless it is an IP address."
So one setting does two jobs. It is the SNI, and it is the name Traefik checks the certificate against, in place of the IP. The lab showed both sides of that:
| Transport on the IP route | Result on 3.7.17 |
|---|---|
| none | 500, doesn't contain any IP SANs |
serverName: app.internal only, CA not trusted | 500, certificate signed by unknown authority |
serverName: other.internal, CA trusted | 500, certificate is valid for app.internal, not other.internal |
serverName: app.internal and rootCAs with the lab CA | 200 |
The third row matters. serverName is not a bypass. Set it to a wrong name and the check still fails. That is why it is the first fix: the 500 goes away only if the certificate really is valid for the name you give.
serverName alone is enough when the certificate already chains to a public CA. Take a backend serving a Let's Encrypt certificate for app.example.com, reached by container IP. The chain check passes against the public roots, and only the name fails. serverName: app.example.com fixes it with nothing else.
serverName does not change the Host header. The backend still saw the client's Host, because passHostHeader defaults to true. If the backend routes by Host, that is a separate setting. How the certificate is picked from the SNI on the backend side is covered in SNI-based routing.
Fix 2: rootCAs, for a private CA or a self-signed certificate#
rootCAs is a list of PEM files that Traefik trusts as CAs for that transport. For a private CA, list the CA's certificate. For a self-signed certificate, list the certificate itself. Go's Verify trusts a certificate that is itself in the root pool, without building a chain. In the lab, a self-signed certificate with the CA flag off still verified that way, with a 200.
One detail is easy to miss. createRootCACertPool in transport.go starts from an empty pool (x509.NewCertPool()), not from the system's CAs. A transport with rootCAs trusts only the files you list. In the lab, a route to https://www.google.com through a transport whose rootCAs held only the lab CA failed with certificate signed by unknown authority. So give each backend that needs a private CA its own transport. Do not add rootCAs to a transport that also serves public sites.
To get a self-signed certificate into a file, read it off the backend once:
openssl s_client -connect 172.18.0.5:8443 -showcerts </dev/null 2>/dev/null \
| openssl x509 > app-cert.pem
openssl x509 -in app-cert.pem -noout -subject -issuer -ext subjectAltNameThe second command shows the subject, the issuer and the SAN list. Read the DNS names from the SAN list. One of them goes in serverName. If the subject and issuer match, the certificate is self-signed and the file goes in rootCAs. If they differ, the issuer is a CA, and you want that CA's certificate instead. Fetch it from a network you trust, and compare its fingerprint with the backend's own copy if you can. Whatever you load here is what Traefik will trust.
The same option exists in static configuration as --serversTransport.rootCAs. It applies to the default transport, the one every service without a named transport uses. It does not help the IP case on its own. With the lab CA loaded globally, the IP route still failed with doesn't contain any IP SANs, because there is no global serverName. The static options list insecureSkipVerify, rootCAs, maxIdleConnsPerHost, timeouts and SPIFFE settings, but no server name.
Docker labels: reference a transport, do not define one#
Labels can point a service at a serversTransport, but cannot create one. The Docker routing reference says the loadbalancer.serverstransport label "Allows to reference a ServersTransport resource that is defined either with the File provider or the Kubernetes CRD one." So a Compose setup needs a file provider next to the Docker provider:
services:
traefik:
image: traefik:v3.7
command:
- --providers.docker=true
- --providers.docker.exposedbydefault=false
- --providers.file.directory=/etc/traefik/dynamic
- --entryPoints.websecure.address=:443
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- ./dynamic:/etc/traefik/dynamic:ro # holds the app-tls transport above
- ./certs:/etc/traefik/certs:ro # holds app-ca.pem
app:
image: example/app-with-builtin-tls
labels:
- traefik.enable=true
- traefik.http.routers.app.rule=Host(`app.example.com`)
- traefik.http.routers.app.entrypoints=websecure
- traefik.http.routers.app.tls=true
- traefik.http.services.app.loadbalancer.server.port=8443
- traefik.http.services.app.loadbalancer.server.scheme=https
- traefik.http.services.app.loadbalancer.serverstransport=app-tls@fileThree labels matter here. server.port names the backend's TLS port. server.scheme=https makes Traefik speak TLS to it; without it, Traefik sends plain HTTP to a TLS port. serverstransport=app-tls@file attaches the transport.
The @file suffix is required. A name with no provider suffix is looked up in the provider that defines the service, which here is Docker. In the lab, serverstransport=rootssn with no suffix made Traefik 3.7.17 log servers transport not found rootssn@docker, with error building proxy for server URL. The route then returned 404, not 500, because the service was never built. If a label fix turns a 500 into a 404, check the suffix first. The wider layout of providers, routers and services is in Traefik routers, services and middlewares.
The file provider version is the same transport, referenced from a service:
http:
services:
app:
loadBalancer:
serversTransport: app-tls
servers:
- url: "https://172.18.0.5:8443"Within the file provider no suffix is needed, since the service and the transport share it.
Fix 3: insecureSkipVerify, last#
insecureSkipVerify: true on a transport makes Traefik accept any certificate. Go's documentation for the field says that in this mode "crypto/tls accepts any certificate presented by the server and any host name in that certificate", and that TLS "is susceptible to machine-in-the-middle attacks". Traffic to the backend is still encrypted. What you lose is any proof that the backend is the one you meant. Anyone who can answer on that IP and port gets the requests, cookies and all. When the backend sits on the same Docker host, that risk may be small. Then again, so is the work of setting serverName and rootCAs. TLS termination, passthrough and re-encryption covers why re-encryption without verification falls short.
It comes in two scopes, and they do not overlap the way people expect:
- Per transport, as
insecureSkipVerify: truein a file-defined serversTransport. It covers only the services that reference it. - Global, as
--serversTransport.insecureSkipVerify=truein static configuration. This sets the default transport. In the lab it fixed every service with no named transport, and none of the services that had one. A service using arootCAstransport still got its 500.
So a global skip does not rescue a broken named transport. And a route that works only because of the global flag will break the day someone gives it a transport of its own. If you must skip verification, do it per transport, for the one backend that needs it, and leave a comment saying why.
Errors serverName cannot fix#
certificate relies on legacy Common Name field, use SANs instead. The certificate puts its name only in the Common Name (CN) field and has no SAN list. Go ignores the CN, and no serverName will match. In the lab, a CN-only certificate in rootCAs, with serverName set to the CN, still failed with this line. Reissue the certificate with a SAN, or fall back to insecureSkipVerify for that one backend.
tls: first record does not look like a TLS handshake. Traefik spoke TLS to a port that answered in plain HTTP. This is also a 500, and also logged at ERROR, because it is the tls.RecordHeaderError that isTLSConfigError matches. Remove scheme=https, or point at the backend's real TLS port.
A backend that wants a client certificate. That is mutual TLS. The certificates option on the same serversTransport supplies one. The setup is in mutual TLS through a proxy.
Which fix to use#
| Your situation | Fix | Verification |
|---|---|---|
| Public CA certificate, reached by IP (Docker) | serverName set to the certificate's DNS name | On |
| Private CA, reached by IP | serverName and rootCAs with the CA certificate | On |
| Self-signed certificate with a SAN | serverName and rootCAs with that certificate | On |
| URL uses a hostname the certificate does not list | serverName set to a name it does list | On |
| Certificate has only a Common Name | Reissue with a SAN; otherwise per-transport insecureSkipVerify | Off for that backend |
| Backend serves plain HTTP | http://, or no scheme=https label | Not TLS |
| Several backends whose certificates cannot be fixed | Per-transport insecureSkipVerify on each; the global flag skips only services with no named transport | Off |
Worked case: a self-signed admin panel behind Docker labels#
Take an application container that serves its admin panel over HTTPS on port 8443 with a certificate it made for itself. Suppose the certificate's SAN list holds panel.local and nothing else. Traefik reaches it through Docker labels with scheme=https and port=8443. Every page returns 500. Walk it through with the rules above.
- On a current release, the log reads
ERR 500 Internal Server Error error="tls: failed to verify certificate: x509: cannot validate certificate for 172.18.0.5 because it doesn't contain any IP SANs". The Docker provider dialed the container's IP. On a release before 3.3.5, you would need--log.level=DEBUGto see this line. - The table points to
serverName. Read the name off the certificate with the twoopensslcommands above. The SAN showsDNS:panel.local, and subject and issuer match, so it is self-signed. - Write a file transport
panel-tlswithserverName: panel.localand add the labelserverstransport=panel-tls@file. The error would now change tocertificate signed by unknown authority. That is the chain check, which the name check had hidden. - Add the saved
app-cert.pemto the transport'srootCAs, and mount it into the Traefik container. Both checks can now pass, so the 500 should become the panel's login page. - If the error at step 3 had been
relies on legacy Common Name fieldinstead,serverNamecould never work. That would be the one place whereinsecureSkipVerify, onpanel-tlsonly, is the right answer, until the certificate is reissued.
One more thing to check: if the application makes a new self-signed certificate each time it starts, the pinned file in rootCAs goes stale on every restart. Then the lasting fix is to give the application a certificate from your own CA and trust that CA.
Where this answer stops applying#
Everything above was observed on Traefik 3.7.17 with the file and Docker providers, plus 3.3.4 and 2.11.21 for the log levels. The status mapping was read in the v2.11.0 and master source, and was not run on every release in between. Kubernetes was not tested: the ServersTransport custom resource carries the same options, but how its secrets are referenced is not covered here. TCP routers use a separate ServersTransportTCP, which this page does not cover either. SPIFFE transports, HTTP/2 to the backend and cipher or TLS version limits were also left out. A 500 that the backend itself sends looks the same to the client, except that its body is the app's own page, not the 21 bytes Internal Server Error. Last, a 500 is not always TLS. If the log line is something else, read that line. Upload failures, for example, show up as 499, 502 or 504, as why uploads through Traefik fail after 60 seconds explains.
Frequently asked questions#
Why does Traefik return 500 instead of 502 for an HTTPS backend?#
Traefik's ComputeStatusCode sends 502 for an end of file or a network error, 504 for a timeout, and 500 for anything else. A certificate verification error is not a network error in Go, so it falls through to 500. A refused connection to the same backend gets 502.
What does "x509: cannot validate certificate because it doesn't contain any IP SANs" mean in Traefik?#
Traefik connected to the backend by IP address and checked that IP against the certificate's names. The certificate lists only DNS names, so the check failed. Set serverName on a serversTransport to one of those DNS names, and Traefik checks that name instead.
Does serverName in Traefik disable certificate verification?#
No. It sets Go's tls.Config.ServerName, which is both the SNI Traefik sends and the name it verifies. In testing, a wrong serverName still failed with certificate is valid for app.internal, not other.internal.
How do I make Traefik trust a self-signed backend certificate?#
Save the certificate to a PEM file and list it in rootCAs on a serversTransport, with serverName set to a DNS name from its SAN list. Go trusts a certificate that is itself in the root pool. The transport then trusts only the files you list, not the public CAs.
Can I define a serversTransport with Docker labels?#
No. Labels can only reference one, with traefik.http.services.<name>.loadbalancer.serverstransport=<transport>@file. Define the transport in a file provider or a Kubernetes CRD. Without the @file suffix, Traefik looks in the Docker provider, logs servers transport not found, and the route returns 404.
Is --serversTransport.insecureSkipVerify=true safe?#
It turns off certificate checks for every service on the default transport. Traffic stays encrypted, but anyone who can answer on the backend's address is trusted. It also does not apply to services that use their own serversTransport. Prefer serverName and rootCAs, and skip verification per transport only when the certificate cannot be fixed.
Why is there nothing in the Traefik log when I get a 500?#
Before v3.3.5 and v2.11.22, Traefik logged backend certificate errors only at DEBUG. Set --log.level=DEBUG or turn on the access log. From those releases on, certificate errors and plain HTTP on a TLS port are logged at ERROR, which shows by default.
Primary sources#
Every normative claim on this page is checked against the specification or the vendor documentation listed here. Where behaviour is version dependent, the version is named in the text.
- Traefik source, pkg/proxy/httputil/proxy.go on master (ComputeStatusCode, ErrorHandlerWithContext, isTLSConfigError)
- Traefik source, pkg/proxy/httputil/proxy.go at v3.3.4 (error logged at debug only)
- Traefik source, pkg/server/service/proxy.go at v2.11.0 ("caused by" debug line, same status mapping)
- Traefik source, pkg/server/service/transport.go on master (createTLSConfig, createRootCACertPool)
- Traefik CHANGELOG (v3.3.5 and v2.11.22, PR 11611 "Error level log for configuration-related TLS errors with backends")
- Traefik documentation, ServersTransport reference
- Traefik documentation, Docker provider routing labels (loadbalancer.server.scheme, loadbalancer.serverstransport)
- Traefik documentation, install configuration options (serversTransport.insecureSkipVerify, serversTransport.rootCAs)
- Go source, crypto/tls/common.go (Config.ServerName, Config.InsecureSkipVerify)
- Go source, crypto/x509/verify.go (HostnameError and UnknownAuthorityError messages, hostname checked before the chain)
Found something wrong, or behaviour that differs on your version? Report it with the version number and a primary source. Anything substantive is fixed in the page and logged on the corrections page. See editorial standards for how pages are researched, sourced and reviewed.
More in troubleshooting proxies#
- 502 vs 503 vs 504: reading proxy errors correctly
- Apache AH00961 failed to enable ssl support: the fix
- Apache AH01102 error reading status line: fix the 502
- Apache AH01114 failed to make connection: the 503 fix
- Apache No protocol handler was valid for the URL: fix
- Caddy 502 dial tcp connection refused: each cause
- Caddy "no certificate available for": each cause
- ERR_TUNNEL_CONNECTION_FAILED: what the proxy answered
- Cntlm vs Px: which one for an NTLM or Kerberos proxy?
- Corporate proxies and developer tooling
- Access-Control-Allow-Origin multiple values: the fix
- curl through a proxy
- Envoy reset reason: connection termination, every cause
- HAProxy 503 No server is available: read the log line
- HAProxy health check failed: every reason decoded
- HAProxy No Private Key found in PEM file: the fix
- Header and body size limits at the proxy
- HTTPS_PROXY: http:// or https://? Tested in 12 clients
- netsh winhttp vs Windows proxy settings: who reads which?
- nginx 413 Request Entity Too Large: find the limit
- nginx 499: what it means, and its ALB, HAProxy, Envoy names
- nginx 502 after Docker restart: fix the stale IP
- nginx in Docker: 502 on proxy_pass localhost, fixed
- nginx drops headers with underscores: why, and the fix
- nginx 400 plain HTTP request sent to HTTPS port: fix
- nginx proxy_cache always MISS: every cause, tested
- Nginx Proxy Manager 502 Bad Gateway: find your cause
- nginx connect() failed to [::1] with localhost: the fix
- nginx (13: Permission denied) to upstream: SELinux fix
- nginx cuts off large downloads: find which of 5 causes
- nginx upstream sent no valid HTTP/1.0 header: the fix
- nginx worker_connections: the right number for a proxy
- The no_proxy environment variable
- POST becomes GET after a redirect: proxies and clients
- A proxy debugging playbook
- Squid TCP_DENIED/403 on every request: the http_access fix
- Squid TCP_MISS/503: decode the log line, find the cause