TLS Certificate and HTTPS Debugging Guide for Web Developers
tlshttpssslopensslcertificatesweb-security

TLS Certificate and HTTPS Debugging Guide for Web Developers

AAllScripts Cloud Editorial Team
2026-11-21
9 min read

A practical TLS certificate troubleshooting checklist covering OpenSSL, curl, certificate chains, browser warnings, and cloud HTTPS renewals.

When HTTPS fails, the certificate itself is only one part of the investigation. This guide provides a reusable TLS certificate troubleshooting checklist for inspecting certificate details, diagnosing browser warnings, verifying chains, testing cloud delivery layers, and confirming that a renewal or configuration change works from a client’s point of view.

Overview

TLS problems often appear similar to users but have different causes. A browser warning may result from an expired certificate, a hostname mismatch, an incomplete certificate chain, an unsupported protocol, a locally untrusted certificate authority, or a proxy presenting a different certificate than the origin server. Treating every warning as an “SSL certificate” problem can lead to changes in the wrong system.

A reliable investigation starts by identifying the exact hostname and delivery path. Ask whether the request goes directly to a web server or through a CDN, cloud load balancer, ingress controller, reverse proxy, service mesh, or corporate inspection proxy. The certificate visible to a browser belongs to the endpoint that terminates TLS for that connection. It may not be the certificate installed on the application server.

Use this sequence as a baseline:

  1. Record the hostname, URL, port, client, time, and exact error message.
  2. Inspect the certificate presented for that hostname.
  3. Check the subject alternative names, validity dates, issuer, and signature details.
  4. Inspect the complete chain and confirm that the client can build trust.
  5. Test protocol negotiation and HTTP behavior separately from certificate identity.
  6. Check every TLS termination layer and validate again after changes.

Do not paste private keys, client certificates, access tokens, or sensitive request data into an online HTTPS certificate checker or debugging tool. Public certificate metadata is generally less sensitive than private connection material, but your organization’s security policy should determine what can be shared.

Checklist by scenario

Scenario 1: Inspect a certificate with OpenSSL

For a public HTTPS endpoint, begin with the hostname that users actually visit. The -servername option sends the TLS Server Name Indication value and is important when several domains share an address.

openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null

Review the output for the leaf certificate, the certificates sent by the server, the negotiated protocol and cipher, and the final verification result. To inspect the leaf certificate in a more readable form, save the relevant PEM block to a file and run:

openssl x509 -in leaf.pem -noout -subject -issuer -dates -ext subjectAltName -fingerprint -sha256

Check these fields:

  • Subject alternative name: The requested hostname must be covered here. Do not rely on the common name alone.
  • Not before and not after: Confirm that the certificate is valid at the time of the request. Also check the system clock on the client and server.
  • Issuer: Confirm that the certificate was issued by the authority expected for the environment.
  • Key and signature details: Compare them with your platform’s supported configuration and internal requirements.
  • Certificate order: The server should send the leaf certificate and the required intermediate certificates, not a private root certificate or an unrelated chain.

Scenario 2: Diagnose a browser HTTPS warning

First capture the exact browser error rather than summarizing it as “SSL failed.” Warnings that mention the certificate being expired, not trusted, issued for another name, or unable to establish a secure connection point to different investigation paths.

Open the browser’s certificate viewer or security panel and compare what it displays with the hostname in the address bar. Browser menus change over time, so use the current security or connection details control for the browser and version being tested. Record the certificate subject alternative names, validity period, issuer, and chain.

Then check the browser’s Network panel. A request can fail during the TLS handshake before an HTTP status code exists, while a successful handshake followed by a redirect, authentication failure, or application error is a separate problem. The Chrome DevTools Network Panel Guide can help separate connection, request, response, and timing issues.

Repeat the test in another browser or from another network only to isolate variables. If one device fails while others succeed, investigate local trust stores, system time, antivirus inspection, enterprise proxy settings, and cached state. If all clients fail, focus on the endpoint, certificate deployment, DNS, and the TLS termination path.

Scenario 3: Check certificate chain errors

A server can present a valid leaf certificate while clients still report a trust error. One common reason is that the server does not send an intermediate certificate required to connect the leaf to a trusted root. Another is that a private or internal certificate authority is not installed in the client trust store.

Use OpenSSL to view the certificates sent by the endpoint:

openssl s_client -connect example.com:443 -servername example.com -showcerts -verify_return_error </dev/null

Interpret the result in context. OpenSSL’s local trust store, operating system, container image, and build can differ from a browser or cloud runtime. A successful test on one machine does not prove that every client trusts the chain. If you have a specific CA bundle for an environment, test with that bundle explicitly:

openssl s_client -connect example.com:443 -servername example.com -CAfile path/to/ca-bundle.pem -verify_return_error </dev/null

For public services, obtain the correct intermediate certificate from the certificate authority or managed certificate service documentation. Do not substitute a root certificate for an intermediate or download certificate files from an unverified source.

Scenario 4: Test HTTP behavior with curl

Use curl to inspect the connection while keeping HTTP behavior visible:

curl -Iv https://example.com/

The output can show the resolved connection, certificate verification result, negotiated protocol, redirects, and response headers. If you need to test a particular address without changing the URL’s hostname or SNI value, use:

curl -Iv --resolve example.com:443:203.0.113.10 https://example.com/

Use a real address only in your own test environment. This technique is useful when DNS has not propagated, when comparing a new load balancer with an existing one, or when checking a specific edge node. Avoid using -k or --insecure as a fix. It disables certificate verification and can hide the condition you are trying to diagnose.

Scenario 5: Validate a renewal or cloud configuration change

After renewing a certificate, verify the public endpoint rather than relying only on a successful deployment message. Check each hostname covered by the service, including alternate names, redirects, API subdomains, and administrative endpoints that are intentionally exposed.

  1. Confirm the certificate is attached to the correct listener, load balancer, ingress, CDN distribution, or reverse proxy.
  2. Confirm the deployment reached all relevant regions, edge locations, or replicas where applicable.
  3. Test the hostname with SNI using OpenSSL.
  4. Run a verbose HTTPS request with curl.
  5. Open the site in a representative browser and inspect its certificate chain.
  6. Check application health, redirects, APIs, webhooks, and non-browser clients.
  7. Remove or disable obsolete certificate attachments only after confirming dependencies.

What to double-check

Observed symptomLikely area to inspect
Certificate is valid but issued for another nameHostname, SNI, DNS target, default virtual host, or wrong listener binding
Certificate has expiredRenewal automation, deployment attachment, clock settings, or an overlooked subdomain
Unknown issuer or unable to build trustMissing intermediate, private CA trust, outdated client trust store, or interception proxy
Handshake fails before an HTTP responseProtocol policy, cipher compatibility, client library, firewall, proxy, or TLS termination layer
Browser works but an API client failsClient runtime, CA bundle, hostname verification, proxy configuration, or protocol support
Only one network or device failsLocal trust store, DNS variation, enterprise inspection, cached DNS, or system time
Renewal appears successful but old certificate remainsCached edge configuration, alternate endpoint, stale listener attachment, or incomplete rollout

Protocol and cipher testing should be intentional. Test the protocol versions your application is expected to support, using the OpenSSL options available in your installed version. For example, a controlled TLS 1.2 test may look like:

openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null

Do not interpret one failed forced-protocol test as proof that the service is insecure or broken. Compare results with normal client behavior, your platform configuration, and the requirements of clients you support. Keep protocol changes in configuration management and test them before production rollout.

Common mistakes

  • Checking the origin instead of the public endpoint: A CDN or load balancer may terminate TLS before traffic reaches the origin.
  • Ignoring SNI: Testing an IP address without the intended hostname can return a default certificate and create a misleading mismatch.
  • Installing only the leaf certificate: Many clients need the server to provide the intermediate certificates needed to build a chain.
  • Using an insecure bypass as a solution: Disabling verification with -k, trusting an arbitrary certificate, or turning off hostname checks changes the symptom, not the configuration.
  • Checking only the expiration date: A current certificate can still have the wrong hostname, wrong issuer, incomplete chain, or incorrect deployment.
  • Assuming all clients share one trust store: Browsers, operating systems, containers, language runtimes, and managed services can use different CA bundles.
  • Testing immediately after a change without recording context: DNS, caches, edge deployment, and connection reuse can produce inconsistent observations. Record the time, location, hostname, and command used.
  • Exposing sensitive diagnostic material: Certificate inspection does not require private keys. Keep keys, client credentials, authorization headers, and internal hostnames out of tickets and public tools.

TLS debugging also benefits from disciplined change management. For automated deployments, validate certificate references and listener configuration before merging. The GitHub Actions YAML validation workflow is useful when certificate renewal or cloud configuration is delivered through CI. Keep secrets and private key material in an approved secrets system; the CI/CD secrets management and rotation playbook provides related guidance.

When to revisit

Revisit this checklist before every certificate renewal, domain migration, CDN or load balancer change, reverse-proxy update, and major client or runtime upgrade. It is also appropriate after unexplained browser warnings, failed API deployments, changes to DNS, or a report that only one region, network, or device cannot connect.

For a maintainable operational workflow, schedule a periodic review of the commands and assumptions used by your team. Check that the installed OpenSSL and curl versions still accept the documented options, that certificate inventory includes every public hostname, and that monitoring tests the same endpoints users and API clients use. Review certificate authority and platform documentation when your managed certificate service changes its interface or delivery model.

After each fix, save a short record containing the affected hostname, observed error, certificate fingerprint or deployment identifier where appropriate, root cause, change made, and validation commands. Do not store private keys or secrets in that record. This turns a one-off incident into a repeatable runbook.

Final action checklist: identify the TLS termination point, capture the exact hostname and error, inspect the presented certificate with SNI, verify SANs and dates, validate the chain with the relevant trust store, test with curl, check cloud and proxy layers, and repeat the test from an affected client after the change. That sequence helps distinguish certificate identity, trust, protocol, routing, and application problems before you make a risky configuration change.

Related Topics

#tls#https#ssl#openssl#certificates#web-security
A

AllScripts Cloud Editorial Team

Technical Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.