TLS Certificate Troubleshooting Guide: Diagnose Expiry, Chain, and Hostname Errors

Overview

TLS certificate errors can look similar in a browser while having very different causes. A certificate may be valid for one hostname but not another, correctly issued but missing an intermediate certificate, current in a load balancer but expired on an origin server, or accepted publicly but rejected by an older client.

Start by recording the exact hostname, port, URL, client, time of the failure, and complete browser or application error. Do not begin by replacing files at random. A controlled sequence makes it easier to identify whether the problem is certificate content, certificate selection, chain delivery, TLS negotiation, or a difference between local and public traffic.

A useful diagnostic order is:

1. Confirm the endpoint and DNS path being tested.
2. Check the certificate dates, subject, issuer, and Subject Alternative Name (SAN) entries.
3. Inspect the complete certificate chain delivered by the server.
4. Verify that the server selects the right certificate for the requested hostname.
5. Test protocol and cipher negotiation with the affected client or tool.
6. Compare public, internal, staging, and origin endpoints.

Keep private keys out of online certificate checkers, chat messages, tickets, and shell history. Public certificates and TLS handshake output are generally useful for diagnosis; private key material is not.

Checklist by scenario

When the browser reports an expired certificate

• Check the certificate's Not Before and Not After values.
• Check the system clock on the affected device. A significantly incorrect clock can make a valid certificate appear expired or not yet valid.
• Confirm which endpoint answered. A CDN, reverse proxy, cloud load balancer, ingress controller, and origin server may each have separate TLS settings.
• Check whether IPv4 and IPv6 resolve to different infrastructure.
• After renewal, verify that the new certificate is installed on every active termination point, not only on the server where the renewal command ran.

Use an API debugging workflow when the failing request is made by an application rather than a browser. Application logs can reveal whether the failure occurs during DNS lookup, TCP connection, certificate validation, or HTTP response handling.

When the hostname does not match

The hostname a client requests must be covered by the certificate's SAN entries. The common name alone should not be treated as a complete hostname check. Look for the exact domain, an appropriate wildcard, or another valid SAN pattern. A wildcard typically covers one label, so a certificate for *.example.com should not automatically be assumed to cover api.dev.example.com.

• Compare the URL hostname with the SAN list, including spelling and subdomain depth.
• Check redirects: the first hostname may be valid while the destination hostname is not.
• Check alternate names used by mobile apps, webhooks, health checks, and internal services.
• Confirm that the server uses SNI correctly when multiple certificates share an IP address.

When the chain is incomplete or untrusted

A server normally needs to send its leaf certificate and the intermediate certificates required by clients to build a trusted path to a root certificate already held by the client. The root certificate is commonly not sent by the server. If a browser works but an API client, container, or command-line tool fails, compare trust stores and chain delivery rather than assuming the leaf certificate is wrong.

To inspect what a server presents, run:

openssl s_client -connect example.com:443 -servername example.com -showcerts

The -servername option matters when the endpoint hosts multiple domains. Review the certificates returned, their order, issuer relationships, and any verification message near the end of the output. For a concise certificate inspection, save a public certificate to a file and run:

openssl x509 -in certificate.pem -noout -subject -issuer -dates -ext subjectAltName

Some providers expose a certificate chain field separately from the leaf certificate. Confirm that the deployment expects a full chain file, and follow the provider's documented certificate and key format rather than combining files by guesswork.

When a cloud load balancer or proxy is involved

• Identify where TLS terminates: edge proxy, CDN, load balancer, ingress, or application server.
• Check the certificate bound to the relevant listener, target, frontend, or hostname rule.
• Verify that the listener rule selects the expected certificate for the request's SNI hostname.
• Check whether the origin connection uses a separate certificate validation path.
• Review deployment history and propagation status before repeating an update.
• Test the public hostname again after the change, rather than testing only an internal node.

Cloud interfaces change, but the underlying questions remain stable: which component terminates TLS, which certificate is attached, which hostname selects it, and whether the next hop is validated separately.

When only certain clients fail

Test from the same client type, network, and runtime that reports the error. A browser and a server-side runtime may use different trust stores and supported protocol versions. A container image may contain an outdated or incomplete CA bundle. An enterprise network may also introduce an inspection proxy with its own certificate path.

Record the client library, runtime version, operating system, container image, proxy settings, and whether the failure occurs on a private network, public network, or both. Avoid weakening certificate verification as a permanent workaround. If a temporary diagnostic bypass is used in a controlled environment, remove it and document the root cause.

What to double-check

DNS and endpoint identity

Resolve the hostname from an affected network and compare the result with the infrastructure you expect. A stale record, split-horizon DNS configuration, or overlooked IPv6 address can send different users to different certificates. Test the canonical hostname, aliases, and any regional or environment-specific names.

Certificate contents

For an openssl certificate check, verify:

• Validity dates and the device clock.
• Subject Alternative Name coverage.
• Issuer and expected certificate authority.
• Key algorithm and signature details required by the client environment.
• Whether the certificate is the newly issued version or an older deployment.

Do not confuse a successful certificate decode with successful HTTPS validation. A certificate can be readable and correctly formatted while still failing because it is expired, mismatched, untrusted, or not the certificate actually served to clients.

Protocol negotiation

If the certificate appears correct but the handshake fails, inspect protocol-version and cipher compatibility. Use a controlled test to compare supported versions, and check the server's TLS policy against the affected client's capabilities. The exact commands and settings vary by operating system, runtime, load balancer, and security policy, so treat old configuration snippets as examples rather than universal recommendations.

Deployment and secret management

Track certificate renewal as a deployment workflow. Confirm where certificate files or managed-certificate references are stored, which service account can update them, and how the change reaches every replica. The environment and secrets workflow guide is useful for separating configuration concerns across local, staging, and production systems.

Common mistakes

• Checking the wrong hostname: Testing an origin IP or internal name does not prove that the public hostname serves the same certificate.
• Ignoring SNI: An OpenSSL test without the requested server name may return a default certificate from a multi-tenant endpoint.
• Installing only the leaf certificate: Some clients need the intermediate chain to be delivered by the server.
• Renewing without checking deployment: Issuing a new certificate does not automatically replace the certificate attached to every proxy or listener.
• Trusting one client as proof: Browser success does not guarantee success for a container, database driver, webhook sender, or older runtime.
• Disabling verification: Skipping hostname or chain validation hides the failure and creates a security exposure rather than solving the deployment problem.
• Sharing sensitive material: Diagnostic output should never include private keys, passwords, or unredacted secret configuration.

When documenting an incident, include the tested hostname, UTC timestamp, client type, endpoint address, certificate fingerprint or serial reference where appropriate, and the exact verification error. This makes a later comparison far more useful than a note that simply says “SSL is broken.”

When to revisit

Revisit this checklist before planned certificate renewals, DNS or CDN migrations, load-balancer changes, ingress upgrades, domain additions, and changes to application runtimes or base images. It is also worth reviewing before seasonal planning cycles when ownership, on-call coverage, or infrastructure topology may have changed.

Keep a small certificate inventory with the hostname, termination point, renewal owner, deployment method, expiry date, and validation command. Schedule an alert with enough lead time to investigate chain and propagation issues, not just enough time to click a renewal button. After each renewal, test from at least one public client and one representative application client.

When workflows or provider interfaces change, update the runbook's commands and screenshots while preserving the diagnostic logic. During the next incident, follow this short action list:

1. Capture the exact error and hostname.
2. Check DNS, endpoint selection, dates, and SAN coverage.
3. Inspect the served chain with SNI enabled.
4. Identify the TLS termination point and certificate binding.
5. Reproduce with the affected client and compare trust stores.
6. Apply the smallest targeted change, then verify publicly and internally.
7. Record the cause and add a preventive check to the renewal workflow.

For broader web troubleshooting, pair this process with a frontend debugging workflow when the page loads but behaves incorrectly, and use a dedicated online developer tools toolkit for safe formatting and inspection tasks that do not involve private credentials.