TLS failures are often caused by a small mismatch between what a server presents, what a client requests, and what a trust store accepts. This guide provides a reusable TLS certificate troubleshooting checklist, with OpenSSL and curl commands for inspecting expiry, subject alternative names (SANs), certificate chains, protocol negotiation, and mutual TLS client authentication.
Overview
When HTTPS or mTLS fails, first identify which part of the connection is breaking. A certificate problem may involve the server certificate, an intermediate certificate, the hostname, the client trust store, TLS version negotiation, or a required client certificate. Replacing a certificate without locating the failure can make diagnosis harder and may interrupt a working deployment.
Use this order when investigating:
- Confirm the endpoint and port being tested.
- Inspect the certificate actually served over the network.
- Check the certificate's validity period and SAN entries.
- Examine whether the server sends the required intermediate chain.
- Compare the issuer with the client's trusted CA set.
- Test protocol and cipher negotiation separately from certificate validation.
- For mTLS, verify the client certificate, private key, and server-side client CA configuration.
Run tests from the same network location as the failing application when possible. A load balancer, service mesh, proxy, ingress controller, or TLS-terminating CDN may present a different certificate than the origin server.
Checklist by scenario
Hostname or SAN certificate mismatch
A certificate is valid for the names listed in its Subject Alternative Name extension, not simply for the name you intended to use. Check the endpoint with:
openssl s_client -connect example.com:443 -servername example.com -showcerts < /dev/null 2> /dev/null | openssl x509 -noout -subject -issuer -dates -ext subjectAltNameConfirm that the requested hostname appears in the SAN list. Pay attention to aliases, regional domains, internal service names, and wildcard scope. A wildcard such as *.example.com generally represents one subdomain level; it should not be assumed to cover the bare domain or deeper names.
Expired or not-yet-valid certificate
Inspect the validity window:
openssl x509 -in server.crt -noout -datesCheck both notBefore and notAfter. If the dates appear reasonable but the client reports a validity error, compare system clocks on the client, proxy, and server. Replace or renew the certificate at the TLS termination point, then verify the live endpoint rather than relying only on a file stored in a deployment repository.
Incomplete certificate chain
A server normally needs to send its leaf certificate and the intermediate certificates required for a client to build a chain to a trusted root. It should not ordinarily send a private key, and adding arbitrary root certificates to the served chain does not repair a trust problem.
Inspect what the server sends:
openssl s_client -connect example.com:443 -servername example.com -showcerts < /dev/nullLook for multiple certificates and review each subject and issuer. An incomplete chain often works in one browser or operating system because that environment has cached or separately installed intermediates, while a container, API client, or minimal Linux image fails. Configure the load balancer, ingress, web server, or secret with the correct full chain in the provider's expected order.
Unknown issuer or trust-store error
Errors such as “unable to get local issuer certificate,” “certificate signed by unknown authority,” or “unable to verify the first certificate” indicate that the client cannot establish trust. Determine whether the endpoint uses a publicly trusted CA, a private enterprise CA, or a development CA. Then confirm that the application is using the intended trust store; runtimes and containers may not use the same CA bundle as the host operating system.
Do not disable certificate verification as a production fix. Instead, install the approved private CA where appropriate, correct the server chain, or use the trust configuration documented by the application runtime.
Protocol negotiation failure
If the certificate looks correct but the connection still fails, test TLS negotiation:
openssl s_client -connect example.com:443 -servername example.com -tls1_2 < /dev/null
openssl s_client -connect example.com:443 -servername example.com -tls1_3 < /dev/null
curl -vI https://example.com/Compare the client and server's supported TLS versions and policies. A protocol error can be caused by an outdated client, an overly restrictive server configuration, an incompatible proxy, or a listener configured for a different protocol. Treat explicit version-forcing options as diagnostic tools unless they are part of a reviewed compatibility configuration.
Mutual TLS client-certificate failure
In mTLS, the server validates a client certificate in addition to presenting its own certificate. Confirm that the client is sending the certificate and that the private key matches it:
openssl x509 -in client.crt -noout -subject -issuer -dates -ext subjectAltName
openssl x509 -noout -modulus -in client.crt | openssl sha256
openssl rsa -noout -modulus -in client.key | openssl sha256
curl -v --cert client.crt --key client.key --cacert ca-bundle.pem https://service.example/The modulus comparison shown is useful for RSA keys; use an equivalent public-key comparison method for other key types. Also check whether the server trusts the CA that issued the client certificate, whether the certificate is within its validity period, and whether authorization rules accept its subject, SAN, or other identity fields. A certificate can be cryptographically valid but rejected by application policy.
What to double-check
| Observed error or symptom | Likely area | First check |
|---|---|---|
| Hostname does not match certificate | SAN or endpoint routing | Confirm the requested hostname and live SAN entries. |
| Certificate has expired | Renewal or deployment | Check the live notAfter value and TLS termination layer. |
| Unable to verify issuer | Trust store or chain | Inspect served intermediates and client CA configuration. |
| Works in a browser, fails in an API client | Different trust store or chain handling | Test from the application host with verbose curl or OpenSSL. |
| Handshake fails before certificate validation | Protocol, cipher, SNI, or proxy | Compare TLS versions and ensure SNI is sent. |
| mTLS reports a client-certificate error | Client identity or server CA policy | Verify certificate/key pairing and the server's trusted client CA. |
Use the -servername option in OpenSSL tests for virtual-hosted HTTPS. Without SNI, a server may return a default certificate that does not represent the requested hostname. For an HTTP-level failure after a successful handshake, inspect status codes, headers, and response bodies separately; TLS may already be working. The HTTP API Error Troubleshooting Reference can help with that next layer.
Common mistakes
- Checking the certificate file instead of the live endpoint: a certificate may be renewed on disk but not loaded by the proxy or load balancer.
- Using the wrong hostname during testing: test the exact DNS name clients use and include SNI.
- Replacing the leaf certificate when the chain is missing: chain order and intermediate deployment may be the actual issue.
- Trusting a root certificate on the server to fix client validation: clients need the appropriate trust anchor; servers need to present the necessary intermediates.
- Disabling verification: this hides configuration errors and removes an important security control.
- Confusing TLS identity with application authorization: successful certificate validation does not necessarily grant access to an API or service.
- Rotating certificates without checking dependent clients: private CA changes, mTLS issuer changes, and trust-store updates should be coordinated.
For Kubernetes deployments, also verify which Secret, ingress resource, gateway, or service-mesh policy is active. A rollout can leave an old certificate serving traffic if the controller has not reloaded the configuration. Apply the same evidence-first approach used for other workload incidents; the Kubernetes Troubleshooting Guide provides a broader pod and deployment diagnostic workflow.
When to revisit
Revisit this checklist before certificate renewal windows, domain migrations, new mTLS integrations, infrastructure moves, and major runtime or operating-system changes. It is also useful after changing a load balancer, ingress controller, service mesh, proxy, CA bundle, or secret-management workflow.
Make certificate checks repeatable rather than dependent on an incident. Record each public and internal endpoint, its TLS termination layer, certificate issuer, SAN coverage, renewal owner, and dependent trust stores. Add automated checks for expiry thresholds, hostname coverage, chain completeness, and representative mTLS handshakes. Test from more than one network location when traffic can take different paths.
During an incident, capture the exact command, hostname, port, client environment, and timestamp used for testing. After renewal or configuration changes, repeat the same test and confirm both success and expected identity. If the failure remains ambiguous, separate the layers: DNS and routing, TCP reachability, TLS handshake, certificate validation, HTTP response, and application authorization. That sequence keeps TLS certificate troubleshooting focused and helps identify which certificate, if any, actually needs replacement.