When HTTPS fails, a certificate can appear valid in one browser and still be rejected by another client. This guide gives you a repeatable TLS certificate troubleshooting workflow using OpenSSL and curl, covering expiry, subject alternative names (SANs), certificate chains, SNI, key usage, trust stores, redirects, and protocol versions. Use it during certificate renewals, domain migrations, monitoring alerts, and production incidents, then revisit the checkpoints on a regular schedule.
Overview
A successful HTTPS connection depends on more than the leaf certificate’s expiration date. The client must receive a certificate whose SAN includes the requested hostname, build a trusted chain to an available root certificate, negotiate a compatible TLS version and cipher, and validate that the certificate is appropriate for server authentication. The endpoint must also present the correct certificate for the hostname, particularly when several domains share an IP address.
Start by defining the exact endpoint that is failing. Record the hostname, port, URL path, client or runtime, network location, and time of the failure. A browser request to https://api.example.test may not exercise the same load balancer, redirect, proxy, or trust store as a container calling an internal service by its service name.
For a first look at the certificate currently presented by a server, use:
openssl s_client -connect example.com:443 -servername example.com -showcerts
The -servername option is important: it sends the hostname through SNI, allowing a virtual host or load balancer to select the intended certificate. Without it, the server may return a default certificate and create a misleading SAN or trust error. To inspect dates and identity fields more compactly, pipe the first certificate into OpenSSL:
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
Use curl to test the complete client behavior rather than only viewing certificate metadata:
curl -vI https://example.com/
Verbose output can show the negotiated connection, redirect location, certificate verification result, and the hostname being contacted. Do not use -k as a fix. It disables certificate verification and is useful only as a tightly controlled diagnostic comparison.
What to track
Create a small inventory for every public and important internal TLS endpoint. Track the hostname, port, certificate issuer, expiration date, SANs, deployment location, renewal owner, and the systems that consume the endpoint. Then check the following failure points.
| What to inspect | Typical symptom | Useful check |
|---|---|---|
| Expiry and validity window | The client reports an expired or not-yet-valid certificate. | Review notBefore and notAfter with openssl x509 -noout -dates. Check the server clock and the client clock. |
| SAN hostname match | The certificate looks trusted, but the requested hostname is rejected. | Inspect subjectAltName. The hostname must match a listed DNS name according to the client’s matching rules; the legacy common name should not be treated as a substitute for a missing SAN. |
| Certificate chain | Browsers work while a script, container, or older runtime reports an issuer or trust error. | Use -showcerts to see what the server sends. Confirm that the server presents the leaf and required intermediate certificates, not a private root certificate. |
| SNI and virtual hosting | The wrong certificate appears for one hostname or one IP address. | Compare an OpenSSL connection with and without -servername, and test the exact hostname through the relevant load balancer or proxy. |
| Key usage and extended key usage | The chain is trusted, but a client rejects the certificate for server use. | Inspect keyUsage and extendedKeyUsage. The certificate should be suitable for TLS server authentication and compatible with the deployment. |
| Trust stores | Only one operating system, language runtime, container, or corporate network fails. | Identify the trust store used by that client. A browser, base image, Java runtime, and operating system may have different certificate authorities installed. |
| Redirect targets | The first URL works, but the final page or API call fails. | Follow redirects with curl -vIL https://example.com/ and inspect every hostname in the chain. |
| TLS protocol compatibility | The client reports a handshake failure before certificate verification. | Compare supported protocol versions and policy on both sides. Prefer current, supported TLS configurations rather than weakening verification. |
For a deeper chain review, save the server response and inspect each certificate separately. A chain can contain a valid leaf while still fail because an intermediate is missing, incorrectly ordered for a particular client, expired, or signed by an authority unavailable in the client’s trust store. If the endpoint is containerized, compare the host and container directly; the image may have a stale or intentionally minimal CA bundle.
Certificate problems often accompany other deployment changes. Validate the surrounding configuration as well: a Docker Compose validation workflow can catch a mounted secret or port mistake, while a Dockerfile linting and build check can help identify image and trust-store issues before release.
Cadence and checkpoints
Certificate monitoring should be continuous, but human review benefits from a predictable cadence. At least monthly, review the inventory for endpoints approaching renewal, recent changes to certificate authority, load balancer configuration, DNS, proxies, and container base images. The exact alert window should reflect your renewal process and operational capacity; do not wait for the final day of validity.
Quarterly, run an active check from more than one relevant environment: a developer workstation, a production-like container, and an external monitoring location when applicable. Record:
- the certificate subject and SAN list returned for each hostname;
- the leaf and intermediate chain presented by each endpoint;
- the negotiated TLS version and whether expected clients can connect;
- the final destination after HTTP redirects;
- the result from the actual application runtime, not only from a browser.
After a renewal or infrastructure migration, perform an immediate checkpoint. Test the public name, direct load balancer path where appropriate, health-check path, and internal service path. Store the command output or monitoring result with the deployment record so an incident responder can compare the new state with the previous one.
How to interpret changes
A changed certificate is not automatically a failure. Issuer, serial number, public key, and intermediate certificates may change during a normal renewal. Focus on whether the hostname coverage, validity period, intended usage, chain, and trust relationship still meet the endpoint’s requirements.
Use the failing client as a clue. If every client fails, inspect the endpoint, deployment, SNI routing, and chain first. If only one client fails, compare its trust store, clock, proxy, TLS policy, and runtime version with a working client. If the failure occurs only after a redirect, test the redirect destination rather than repeatedly inspecting the original certificate.
Separate verification failures from handshake failures. A verification error usually points to identity, expiry, chain, or trust. A handshake failure can instead involve protocol versions, cipher policy, client certificates, unsupported signature algorithms, or a proxy terminating TLS. OpenSSL output is useful evidence, but reproduce the request with the application’s actual runtime when possible.
Do not “solve” an unknown certificate by disabling verification, adding a broad trust exception, or copying a production root into an image without documenting why. Those actions can hide the original problem and create a larger trust boundary. Make the smallest controlled change, retest from the affected client, and remove temporary diagnostic settings.
When to revisit
Revisit this checklist monthly or quarterly, and immediately after certificate renewal, domain or DNS migration, load balancer changes, CDN or reverse-proxy changes, container base-image updates, operating-system updates, trust-store changes, or TLS policy changes. Return to it when monitoring reports an expiry warning, when one client begins failing while another works, or when a new hostname is added to an existing service.
Keep a short incident record for each recurring issue: exact hostname, timestamp, client, command used, certificate fingerprint or serial, chain received, redirect target, and remediation. On the next review, compare those records rather than relying on memory. A practical final check is:
- Run
curl -vIagainst the exact URL and follow redirects. - Run
openssl s_clientwith the correct hostname in-servername. - Confirm expiry, SANs, issuer, key usage, and the complete served chain.
- Repeat the test from the failing runtime, host, container, or network.
- Record the result and schedule the next review before closing the change.
For related infrastructure checks, use the HTTP status code debugging matrix to distinguish transport problems from application responses, and the Terraform plan review checklist to inspect infrastructure changes that may have altered the endpoint.