{"id":14,"date":"2026-07-16T00:00:00","date_gmt":"2026-07-16T00:00:00","guid":{"rendered":"http:\/\/\/var\/www\/html\/?p=14"},"modified":"2026-07-21T01:02:30","modified_gmt":"2026-07-21T01:02:30","slug":"caddy-reverse-proxy-tls-handshake-failed-verification-error-on-windows-wsl2-ubuntu","status":"publish","type":"post","link":"https:\/\/butitworkedlocal.com\/caddy-reverse-proxy-tls-handshake-failed-verification-error-on-windows-wsl2-ubuntu\/","title":{"rendered":"Caddy Reverse Proxy: Resolving TLS Handshake Failed Verification (x509) on Windows WSL2 Ubuntu"},"content":{"rendered":"\n

Troubleshoot 'TLS handshake failed verification' when Caddy in WSL2 acts as a reverse proxy. Learn to manage certificate trust for backend services.<\/strong><\/p>\n\n\n

Caddy Reverse Proxy: Resolving TLS Handshake Failed Verification (x509) on Windows WSL2 Ubuntu<\/h2>\n

When operating Caddy as a reverse proxy within a Windows Subsystem for Linux 2 (WSL2) Ubuntu environment, you might encounter errors related to TLS handshake verification. This typically happens when Caddy attempts to establish a secure connection to your backend service (e.g., a web application, API, or another internal server) but fails to validate the backend's TLS certificate. The result is an inability for Caddy to proxy requests, leading to unresponsive services or error pages for your users.<\/p>\n

This guide will walk you through diagnosing and resolving the common causes of "TLS handshake failed verification" errors, particularly focusing on certificate trust issues within the WSL2 environment.<\/p>\n

Symptom & Error Signature<\/h3>\n

Users attempting to access your service through Caddy will likely see generic browser errors such as NET::ERR_CERT_INVALID<\/code>, ERR_SSL_PROTOCOL_ERROR<\/code>, or 502 Bad Gateway<\/code> if Caddy cannot successfully connect to the backend.<\/p>\n

The most telling sign will be in your Caddy logs. You'll observe entries similar to these, indicating Caddy's struggle to trust the backend certificate:<\/p>\n

ERROR   http.log.error  reverse proxy: selected backend is unhealthy: TLS handshake failed: remote error: tls: handshake failure\nERROR   http.log.error  reverse proxy: x509: certificate signed by unknown authority\nERROR   http.log.error  reverse proxy: tls: failed to verify certificate: x509: certificate signed by unknown authority\nERROR   http.log.error  reverse proxy: dial tcp 172.17.0.2:443: connect: connection refused\n<\/code><\/pre>\n
The specific messages x509: certificate signed by unknown authority<\/code> or tls: failed to verify certificate<\/code> are key indicators of a certificate trust problem.<\/p>\n
Root Cause Analysis<\/h3>\n
The "TLS handshake failed verification" error, especially with x509: certificate signed by unknown authority<\/code>, means that Caddy, acting as a client to your backend server, received a certificate but couldn't validate its authenticity using its list of trusted Certificate Authorities (CAs). This usually stems from one or more of the following:<\/p>\n
    \n
  1. Self-Signed Certificates:<\/strong> The backend server is using a self-signed TLS certificate. These certificates are not issued by a publicly trusted CA and therefore are inherently untrusted by default.<\/li>\n
  2. Internal CA Certificates:<\/strong> The backend server's certificate is issued by an internal or private Certificate Authority (CA) specific to your organization or development setup. WSL2's Ubuntu instance, by default, only trusts widely recognized public CAs.<\/li>\n
  3. Missing Intermediate Certificates:<\/strong> The backend server might be serving its certificate without providing the full chain of intermediate certificates, preventing Caddy from building a trusted path to a known root CA.<\/li>\n
  4. Incorrect Caddy Configuration:<\/strong> The reverse_proxy<\/code> directive might be pointing to the wrong IP address or port, or is missing necessary TLS configuration options.<\/li>\n
  5. Network\/Firewall Issues:<\/strong> Though less likely to cause a "TLS handshake failed verification" specifically (which implies a connection was made and a certificate received), underlying network connectivity issues or firewall blocks could result in similar high-level errors like 502 Bad Gateway<\/code> and precede this specific TLS error, showing as connection refused<\/code> initially.<\/li>\n
  6. Expired or Invalid Certificates:<\/strong> The backend's certificate might be expired, revoked, or have a hostname mismatch, leading to validation failure.<\/li>\n<\/ol>\n
    The most prevalent causes for WSL2 scenarios involving internal services are self-signed or internal CA certificates, as WSL2's Ubuntu environment needs explicit instruction to trust them.<\/p>\n
    Step-by-Step Resolution<\/h3>\n
    Follow these steps to diagnose and resolve the TLS handshake verification error.<\/p>\n
    1. Verify Caddy Configuration<\/h4>\n
    First, ensure your Caddyfile<\/code>'s reverse_proxy<\/code> directive is correctly configured to point to your backend service's address and port.<\/p>\n
    yourdomain.com {\n    reverse_proxy https:\/\/your_backend_ip_or_hostname:port {\n        # Other directives if needed\n    }\n}\n<\/code><\/pre>\n
    Make sure you're using https:\/\/<\/code> if your backend is serving over TLS, which is the assumption for this error.<\/p>\n
    2. Inspect Caddy Logs for Detailed Error Messages<\/h4>\n
    The Caddy logs are your primary diagnostic tool. If Caddy is running as a systemd<\/code> service, you can retrieve logs using journalctl<\/code>.<\/p>\n
    sudo journalctl -u caddy -f --since "5 minutes ago"\n<\/code><\/pre>\n
    Look for the exact error message string. x509: certificate signed by unknown authority<\/code> is a strong indicator that Caddy does not trust the CA that signed your backend's certificate.<\/p>\n
    3. Determine Your Backend Certificate's Origin<\/h4>\n
    You need to know if your backend's TLS certificate is:<\/p>\n
      \n
    • Issued by a publicly trusted CA (e.g., Let's Encrypt, DigiCert).<\/li>\n
    • Self-signed.<\/li>\n
    • Issued by an internal\/private CA.<\/li>\n<\/ul>\n
      You can inspect the certificate directly from WSL2 using openssl<\/code>. Replace your_backend_ip_or_hostname:port<\/code> with your actual backend's address.<\/p>\n
      openssl s_client -connect your_backend_ip_or_hostname:port -showcerts <\/dev\/null 2>\/dev\/null | openssl x509 -text -noout | grep "Issuer:|Subject:|Not Before:|Not After:"\n<\/code><\/pre>\n
      Pay close attention to the Issuer<\/code> field. If it's your own company, a custom name, or the same as Subject<\/code>, it's likely a self-signed or internal CA certificate.<\/p>\n
      4. Add the CA Certificate to WSL2's Trust Store (Recommended)<\/h4>\n
      This is the most robust solution for internal or self-signed certificates. You need to obtain the root or intermediate CA certificate that signed your backend's certificate and add it to your WSL2 Ubuntu instance's system-wide trust store.<\/p>\n
      a. Obtain the CA Certificate File<\/h5>\n
      You might receive this file from your internal IT department, or you can extract it if you have access to the backend server. If you only have the backend server's leaf<\/em> certificate, you'll need the CA certificate that signed it.<\/p>\n
      The certificate file must<\/strong> be in PEM format (base64-encoded ASCII with -----BEGIN CERTIFICATE-----<\/code> and -----END CERTIFICATE-----<\/code> headers) and typically have a .crt<\/code> extension.<\/p>\n<\/blockquote>\n
      If you don't have the .crt<\/code> file directly, you can often extract it from the backend server's certificate chain. For example, if you can curl<\/code> your backend (even if it fails validation, you might get the cert):<\/p>\n
      # This command tries to fetch the certificate chain from your backend\n# and save it as backend_chain.pem. You'll then need to identify\n# and extract the CA cert from this chain.\nopenssl s_client -showcerts -verify 5 -connect your_backend_ip_or_hostname:port < \/dev\/null | awk '\/BEGIN CERTIFICATE\/,\/END CERTIFICATE\/{ print $0 }' > backend_chain.pem\n<\/code><\/pre>\n
      Examine backend_chain.pem<\/code>. You'll typically find multiple certificates. The root or intermediate CA certificate is usually one that doesn't<\/em> have Subject<\/code> matching your backend's domain but does<\/em> have Issuer<\/code> matching its own Subject<\/code> (for a root) or an upstream CA (for an intermediate). Extract this specific CA certificate into its own .crt<\/code> file (e.g., my-internal-ca.crt<\/code>).<\/p>\n
      b. Install the CA Certificate in WSL2 Ubuntu<\/h5>\n
        \n
      1. Copy your .crt<\/code> file (e.g., my-internal-ca.crt<\/code>) into the \/usr\/local\/share\/ca-certificates\/<\/code> directory within your WSL2 Ubuntu instance.<\/p>\n
        sudo cp \/path\/to\/my-internal-ca.crt \/usr\/local\/share\/ca-certificates\/\n<\/code><\/pre>\n<\/li>\n
      2. Update the system's CA certificate store.<\/p>\n
        sudo update-ca-certificates\n<\/code><\/pre>\n
        You should see output similar to Adding new cert into \/etc\/ssl\/certs\/<\/code> and 1 added, 0 removed; done.<\/code>.<\/p>\n<\/li>\n
      3. Restart Caddy to pick up the new trust store.<\/p>\n
        sudo systemctl restart caddy\n<\/code><\/pre>\n
        Check Caddy logs again (sudo journalctl -u caddy -f<\/code>) to ensure the error is resolved.<\/p>\n<\/li>\n<\/ol>\n
        5. Configure Caddy with tls_trusted_ca_certs<\/code> (Alternative\/Specific)<\/h4>\n
        If you prefer not to add the CA certificate system-wide, or if you need more granular control, you can specify the trusted CA certificate directly in your Caddyfile<\/code> for a specific reverse_proxy<\/code> block.<\/p>\n
        yourdomain.com {\n    reverse_proxy https:\/\/your_backend_ip_or_hostname:port {\n        tls_trusted_ca_certs \/path\/to\/my-internal-ca.crt\n    }\n}\n<\/code><\/pre>\n
        Ensure the \/path\/to\/my-internal-ca.crt<\/code> is accessible by the Caddy user and specifies the path within your WSL2 filesystem<\/em>.<\/p>\n<\/blockquote>\n
        After modifying your Caddyfile<\/code>, reload Caddy:<\/p>\n
        sudo systemctl reload caddy\n# Or if reload fails to pick up all changes:\nsudo systemctl restart caddy\n<\/code><\/pre>\n
        6. Temporarily Skip TLS Verification (Development\/Last Resort)<\/h4>\n
        Using tls_insecure_skip_verify<\/code> is highly discouraged in production environments<\/strong>. It completely disables TLS certificate validation, making your connection vulnerable to Man-in-the-Middle (MITM) attacks and compromising the security of your data. Only use this for development or debugging where security implications are fully understood and accepted.<\/p>\n<\/blockquote>\n
        If you're in a development environment and absolutely need to proceed without certificate validation, you can instruct Caddy to skip verification:<\/p>\n
        yourdomain.com {\n    reverse_proxy https:\/\/your_backend_ip_or_hostname:port {\n        tls_insecure_skip_verify\n    }\n}\n<\/code><\/pre>\n
        Reload or restart Caddy after this change. Remove this directive as soon as you implement a proper certificate trust solution.<\/p>\n
        7. Verify Network Connectivity and DNS Resolution<\/h4>\n
        If you're still facing issues, or if Caddy logs initially showed connection refused<\/code> before TLS handshake failed<\/code>, verify network connectivity from your WSL2 instance to the backend.<\/p>\n
          \n
        1. Ping the backend:<\/strong><\/p>\n
          ping your_backend_ip_or_hostname\n<\/code><\/pre>\n<\/li>\n
        2. Test direct HTTPS connection with curl<\/code> from WSL2:<\/strong><\/p>\n
          curl -v https:\/\/your_backend_ip_or_hostname:port\/your_health_check_path\n<\/code><\/pre>\n
          This curl<\/code> command will show detailed TLS handshake information and certificate validation steps, similar to how Caddy operates. If curl<\/code> fails with SSL certificate problem: unable to get local issuer certificate<\/code>, it confirms the trust store issue. If it fails with Connection refused<\/code>, it indicates a network or firewall problem.<\/p>\n<\/li>\n
        3. Check DNS Resolution:<\/strong> If using a hostname, ensure WSL2 can resolve it. Add an entry to \/etc\/hosts<\/code> if it's an internal hostname not resolved by your DNS server.<\/p>\n
          # Example \/etc\/hosts entry\n192.168.1.100   your_backend_hostname\n<\/code><\/pre>\n<\/li>\n<\/ol>\n
          8. Check Backend Certificate Expiry and Hostname<\/h4>\n
          Ensure the backend server's certificate is not expired and that its Subject Alternative Name<\/code> (SAN) or Common Name<\/code> (CN) matches the hostname or IP address Caddy is using to connect.<\/p>\n
          openssl s_client -connect your_backend_ip_or_hostname:port -showcerts <\/dev\/null 2>\/dev\/null | openssl x509 -text -noout | grep -E "Subject Alternative Name|Not Before:|Not After:"\n<\/code><\/pre>\n
          If the certificate is expired or the hostname doesn't match, you'll need to renew or re-issue the backend's certificate.<\/p>\n
          By systematically following these steps, you should be able to diagnose and resolve the "TLS handshake failed verification" error with Caddy acting as a reverse proxy in your Windows WSL2 Ubuntu environment. Prioritize adding trusted CA certificates to the system store for a secure and robust solution.<\/p>\n","protected":false},"excerpt":{"rendered":"
          Troubleshoot ‘TLS handshake failed verification’ when Caddy in WSL2 acts as a reverse proxy. Learn to manage certificate trust for backend services.<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[36,43,40,37,28,13,12,42],"class_list":["post-14","post","type-post","status-publish","format-standard","hentry","category-web-server","tag-caddy","tag-certificate-trust","tag-devops","tag-reverse-proxy","tag-tls","tag-ubuntu","tag-wsl2","tag-x509"],"_links":{"self":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts\/14","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/comments?post=14"}],"version-history":[{"count":2,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts\/14\/revisions"}],"predecessor-version":[{"id":262,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts\/14\/revisions\/262"}],"wp:attachment":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/media?parent=14"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/categories?post=14"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/tags?post=14"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}