How do I diagnose a certificate verification failure without bypassing TLS checks?
A TLS verification failure can result from an incorrect hostname, expired certificate, missing intermediate chain, untrusted private CA or incorrect client clock. Identify which check failed before changing trust settings. Disabling verification removes the protection that detects the problem and is not a successful repair.
Before you start
- The actual hostname and a client with an accurate clock.
- An approved CA certificate file only when the service intentionally uses a private organisational CA.
Instructions
1. Read the error from a credential-free request
Use a bounded request to the exact hostname. Verbose output can contain headers and network details, so redact it before sharing and do not add real tokens or cookies.
curl --verbose --head --connect-timeout 5 --max-time 15 https://app.example.com/Keeps normal certificate verification enabled and reports handshake diagnostics.
2. Match the failure to its cause
Compare certificate names and validity with the requested hostname and client time. For issuer errors, check the server’s intermediate chain and the client trust store; the same symptom can originate on either side.
3. Use approved private-CA trust when intended
Only use a CA file obtained through your organisation’s trusted distribution process. Do not trust a certificate merely because the failing server supplied it.
curl --cacert /path/to/approved-ca.pem --head --max-time 15 https://app.example.com/Adds the explicitly selected trusted CA file for this request while retaining hostname and certificate verification.
Check the result
- The same request succeeds with the intended trust configuration and no verification bypass.
Troubleshooting
- It works on one computer only
- Compare clock, trust store, proxy interception and curl’s TLS backend. A browser and command-line client may use different trust configuration.
Official references
Use the documentation for your installed version when a flag, service name or platform feature differs.