Troubleshooting

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.

· 17 min read · How we verify this

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 SANs means Traefik connected by IP address (the Docker provider always does) and the certificate names only hostnames. Set serverName on 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 authority means the certificate does not chain to a CA Traefik trusts. Put your private CA, or the self-signed certificate itself, in rootCAs. That list replaces the public CAs for that transport. A self-signed backend normally needs both serverName and rootCAs.
  • 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 for name@docker, logged servers 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. insecureSkipVerify also 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:

yaml
# 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 itself

Then 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 meansFix
tls: failed to verify certificate: x509: cannot validate certificate for 172.18.0.5 because it doesn't contain any IP SANsTraefik checked the IP it dialed; the certificate has no IP in itserverName set to a DNS name the certificate lists
... x509: certificate is valid for app.internal, not appTraefik checked the hostname in the URL, such as a Compose service nameserverName: app.internal
... x509: certificate signed by unknown authorityThe certificate does not chain to a trusted CArootCAs with your CA, or the self-signed certificate
... x509: certificate relies on legacy Common Name field, use SANs insteadThe certificate has a name only in its Common NameReissue it with a SAN; no Traefik setting fixes this except insecureSkipVerify
tls: first record does not look like a TLS handshakeThe backend port speaks plain HTTPUse http://, or drop scheme=https from the labels
servers transport not found app-tls@docker, and the route gives 404A label referenced a transport without @fileAdd @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:

  1. If the error is an end of file (io.EOF), send 502.
  2. If the request was canceled, send 499.
  3. If the error is a Go net.Error (a network error), send 504 if it was a timeout, else 502.
  4. 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:

text
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:

text
# 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 routeResult on 3.7.17
none500, doesn't contain any IP SANs
serverName: app.internal only, CA not trusted500, certificate signed by unknown authority
serverName: other.internal, CA trusted500, certificate is valid for app.internal, not other.internal
serverName: app.internal and rootCAs with the lab CA200

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:

bash
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 subjectAltName

The 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:

yaml
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@file

Three 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:

yaml
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: true in a file-defined serversTransport. It covers only the services that reference it.
  • Global, as --serversTransport.insecureSkipVerify=true in 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 a rootCAs transport 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 situationFixVerification
Public CA certificate, reached by IP (Docker)serverName set to the certificate's DNS nameOn
Private CA, reached by IPserverName and rootCAs with the CA certificateOn
Self-signed certificate with a SANserverName and rootCAs with that certificateOn
URL uses a hostname the certificate does not listserverName set to a name it does listOn
Certificate has only a Common NameReissue with a SAN; otherwise per-transport insecureSkipVerifyOff for that backend
Backend serves plain HTTPhttp://, or no scheme=https labelNot TLS
Several backends whose certificates cannot be fixedPer-transport insecureSkipVerify on each; the global flag skips only services with no named transportOff

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.

  1. 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=DEBUG to see this line.
  2. The table points to serverName. Read the name off the certificate with the two openssl commands above. The SAN shows DNS:panel.local, and subject and issuer match, so it is self-signed.
  3. Write a file transport panel-tls with serverName: panel.local and add the label serverstransport=panel-tls@file. The error would now change to certificate signed by unknown authority. That is the chain check, which the name check had hidden.
  4. Add the saved app-cert.pem to the transport's rootCAs, and mount it into the Traefik container. Both checks can now pass, so the 500 should become the panel's login page.
  5. If the error at step 3 had been relies on legacy Common Name field instead, serverName could never work. That would be the one place where insecureSkipVerify, on panel-tls only, 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.

  1. Traefik source, pkg/proxy/httputil/proxy.go on master (ComputeStatusCode, ErrorHandlerWithContext, isTLSConfigError)
  2. Traefik source, pkg/proxy/httputil/proxy.go at v3.3.4 (error logged at debug only)
  3. Traefik source, pkg/server/service/proxy.go at v2.11.0 ("caused by" debug line, same status mapping)
  4. Traefik source, pkg/server/service/transport.go on master (createTLSConfig, createRootCACertPool)
  5. Traefik CHANGELOG (v3.3.5 and v2.11.22, PR 11611 "Error level log for configuration-related TLS errors with backends")
  6. Traefik documentation, ServersTransport reference
  7. Traefik documentation, Docker provider routing labels (loadbalancer.server.scheme, loadbalancer.serverstransport)
  8. Traefik documentation, install configuration options (serversTransport.insecureSkipVerify, serversTransport.rootCAs)
  9. Go source, crypto/tls/common.go (Config.ServerName, Config.InsecureSkipVerify)
  10. 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#