Cybersecurity / Networking

SSL Certificate Chain Incomplete Error on API Clients

When an SSL certificate works fine in a browser but fails specifically for API clients, command-line tools, or certain programming language HTTP libraries, it almost always means the server is only serving its own leaf certificate without the required intermediate certificate(s) — browsers often compensate for this gap automatically, while many non-browser clients correctly do not.

The Problem

A browser visiting the site shows a valid, trusted HTTPS connection with no warnings. But an API client, a curl request, or a backend service connecting to the same endpoint fails:

SSL certificate problem: unable to get local issuer certificate
curl: (60) SSL certificate problem: unable to get local issuer certificate

x509: certificate signed by unknown authority
Certificate chain Root CA Intermediate often missing! Leaf (your domain)

Why It Happens

A certificate's trust chain typically has three levels: a root certificate authority (trusted by default in operating systems and browsers), one or more intermediate certificates (which the root has signed), and your domain's own leaf certificate (signed by an intermediate, not directly by the root). Servers need to serve the leaf certificate along with the intermediate certificate(s) — most clients don't automatically fetch missing intermediates on their own. This causes issues specifically because:

  • Many browsers implement AIA (Authority Information Access) chasing, which automatically fetches a missing intermediate certificate from a URL embedded in the leaf certificate itself if the server doesn't provide it — this is a browser-specific convenience feature that most command-line tools and programming language HTTP libraries simply don't implement
  • The server's TLS configuration only has the leaf certificate installed, without the accompanying intermediate certificate bundle that the certificate authority provided alongside it during issuance
  • A certificate renewal process replaced the leaf certificate but didn't correctly update the accompanying intermediate chain file, if the certificate authority rotated which intermediate certificate they're currently using

The Fix

First, confirm the chain is actually incomplete using an external SSL testing tool, which explicitly reports on chain completeness separately from basic certificate validity — many browsers won't surface this as clearly as a dedicated diagnostic tool will.

Directly test what your server actually serves, using OpenSSL, which does not perform the same automatic chain-completion browsers do:

openssl s_client -connect your-domain.com:443 -showcerts

If only one certificate appears in the output (rather than the leaf plus at least one intermediate), this confirms the server isn't serving the full chain.

Fix the server configuration to serve the complete certificate chain, not just the leaf certificate. The exact method depends on your web server, but the general pattern for Nginx looks like:

# nginx.conf
ssl_certificate /path/to/fullchain.pem;  # leaf + intermediate(s) combined
ssl_certificate_key /path/to/private.key;

The critical detail is that fullchain.pem (a common naming convention, particularly with Let's Encrypt/Certbot) contains the leaf certificate AND the intermediate certificate(s) concatenated together in the correct order — using only the leaf certificate file (sometimes named just cert.pem) omits the intermediate entirely, which is exactly the incomplete-chain scenario causing this error.

If you're using Let's Encrypt with Certbot, it typically generates both files automatically, and using fullchain.pem rather than cert.pem in your server configuration is the correct, complete choice:

ls /etc/letsencrypt/live/your-domain.com/
# cert.pem      - leaf only
# fullchain.pem - leaf + intermediate (use this one)

After correcting the configuration, restart or reload your web server, then re-test with OpenSSL to confirm the full chain now appears:

sudo systemctl reload nginx
openssl s_client -connect your-domain.com:443 -showcerts

Still Not Working?

If you've confirmed the full chain is being served correctly but a specific client still reports a chain error, check whether that client has an outdated or incomplete local root certificate store — older systems, especially older mobile OS versions or embedded devices with infrequently updated certificate stores, can lack a newer root CA that a certificate authority has since started using, producing a trust error that has nothing to do with your server's own configuration at all, and instead requires updating the client system's own trusted root store.

You might also like