跳到主要内容

Nginx: ssl_stapling ignored, issuer certificate not found

You enabled OCSP stapling, reloaded nginx, and got one line in error.log that quietly turns the feature back off:

nginx: [warn] "ssl_stapling" ignored, issuer certificate not found for certificate "/etc/nginx/ssl/example.com.crt"

Nothing breaks, no handshake fails, and clients still connect — which is exactly why this warning gets ignored for months. The cause is almost always the same: the file referenced by ssl_certificate contains only your leaf (server) certificate, so nginx has no idea which CA signed it and cannot build the chain it needs to ask that CA’s OCSP responder for a signed status. This article covers why the chain matters, how to diagnose it in five commands, two fixes that work, and how to prove the staple is actually being sent.

1. What the Warning Actually Means

OCSP stapling is a caching trick with a chain-of-trust prerequisite. To staple, nginx must:

  1. Read your server certificate and find its issuer (the intermediate CA that signed it).
  2. Read the OCSP responder URL embedded in the certificate’s Authority Information Access (AIA) extension.
  3. Resolve that hostname, POST a DER-encoded OCSP request, and cache the signed response.
  4. Attach that response to the TLS handshake so clients skip their own OCSP lookup.

Step 1 is where it fails. nginx searches the certificates loaded from ssl_certificate and ssl_trusted_certificate looking for a certificate whose subject matches your leaf’s issuer field. If your ssl_certificate file holds a single BEGIN CERTIFICATE block, there is nothing to match, so nginx logs the warning and disables stapling for that server block.

Note the wording: ignored. nginx does not exit, does not fail nginx -t, and does not retry later. The feature is off until you fix the configuration and reload.

2. How nginx Builds the Chain (and Why Order Matters)

nginx is not a chain-building wizard like a browser. It does a fairly literal lookup:

  • ssl_certificate — the leaf first, then zero or more intermediates. This is what is actually sent to clients in the handshake.
  • ssl_trusted_certificate — a separate bundle used for verification: OCSP response verification when ssl_stapling_verify on, and client-certificate verification when ssl_verify_client is used.
  • System CA store — used only when no ssl_trusted_certificate is configured, and only if nginx was built against OpenSSL with default verify paths.

Two consequences people miss constantly:

  • The root certificate is not the issuer of your leaf. Putting only ISRG Root X1 or DigiCert Global Root G2 in ssl_trusted_certificate will produce the exact same warning. The issuer is the intermediate.
  • Only the leaf gets stapled. nginx does not staple OCSP responses for intermediates, and each certificate configured with a ssl_certificate directive (for example an RSA and an ECDSA pair) needs its own resolvable issuer.

Verify your build supports stapling before you debug further:

nginx -V 2>&1 | tr ' ' '
' | grep -E 'nginx version|with-http_ssl_module|openssl'

ssl_stapling has existed since nginx 1.3.7 and multiple ssl_certificate directives since 1.11.0, so version problems are rare — but custom builds linked against a stripped OpenSSL occasionally lack OCSP support entirely.

3. Diagnose Before You Edit Anything

Run these five commands against your actual files and your actual server. Guessing wastes more time than checking.

3.1 How many certificates are in the file?

grep -c 'BEGIN CERTIFICATE' /etc/nginx/ssl/example.com.crt

1 means leaf-only and confirms the diagnosis. 2 or more means the chain is present and the problem is elsewhere (wrong issuer, wrong order, or an unrelated warning).

3.2 Who signed the leaf?

openssl x509 -in /etc/nginx/ssl/example.com.crt -noout -subject -issuer

Example output:

subject=CN = example.com
issuer=C = US, O = Let's Encrypt, CN = R11

The issuer line is the certificate nginx must be able to find inside your configured files.

3.3 Does the chain verify locally?

openssl verify -untrusted /etc/nginx/ssl/chain.pem /etc/nginx/ssl/example.com.crt

Expected: example.com.crt: OK. Anything else means chain.pem is missing an intermediate or contains the wrong one.

3.4 Does the certificate even have an OCSP responder URL?

openssl x509 -in /etc/nginx/ssl/example.com.crt -noout -ocsp_uri

Empty output is decisive: there is no OCSP service for this certificate. See the FAQ on Let’s Encrypt and OCSP deprecation — the correct fix there is to turn stapling off, not to add certificates.

3.5 What is the server actually sending?

openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -E '^ *[0-9]+ s:|^ *i:'

A healthy chain looks like this:

 0 s:CN = example.com
   i:C = US, O = Let's Encrypt, CN = R11
 1 s:C = US, O = Let's Encrypt, CN = R11
   i:C = US, O = Internet Security Research Group, CN = ISRG Root X1

If you only see entry 0, you are serving a leaf-only chain. That is a second, independent bug: clients that cannot fetch the intermediate via AIA will fail with unable to get local issuer certificate.

4. Fix 1 — Serve the Full Chain in ssl_certificate

This is the simplest fix and the one you should apply anyway, because it also repairs the handshake for clients that do not fetch intermediates.

If your CA hands you separate files, concatenate leaf first, intermediates second:

cat example.com.crt intermediate.crt > fullchain.pem

If you already have a bundle and want to strip the leaf to build a separate trust file:

awk 'BEGIN{n=0} /-----BEGIN CERTIFICATE-----/{n++} n>=2' fullchain.pem > chain.pem

With certbot-managed certificates you do not need to build anything — use the paths certbot already maintains:

  • /etc/letsencrypt/live/example.com/fullchain.pem → ssl_certificate
  • /etc/letsencrypt/live/example.com/chain.pem → ssl_trusted_certificate
  • /etc/letsencrypt/live/example.com/privkey.pem → ssl_certificate_key

Working server block:

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate         /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key     /etc/nginx/ssl/example.com.key;
    ssl_trusted_certificate /etc/nginx/ssl/chain.pem;

    ssl_stapling on;
    ssl_stapling_verify on;

    resolver 1.1.1.1 8.8.8.8 valid=300s;
    resolver_timeout 5s;
}

Two details that cause most remaining failures:

  • resolver is mandatory unless you set ssl_stapling_responder explicitly. nginx must resolve the OCSP hostname itself; it does not use /etc/resolv.conf. Without it you trade one warning for another.
  • The chain file must be readable by the nginx worker user. A root-only 600 file on chain.pem produces confusing failures after reload.

Then validate and reload:

nginx -t && nginx -s reload

5. Fix 2 — Use ssl_trusted_certificate for the Issuer

If you must keep a leaf-only ssl_certificate (some legacy clients or appliances demand it, though this is rare and usually misguided), point ssl_trusted_certificate at a bundle containing the intermediate and the root:

ssl_certificate         /etc/nginx/ssl/example.com.crt;
ssl_certificate_key     /etc/nginx/ssl/example.com.key;
ssl_trusted_certificate /etc/nginx/ssl/chain.pem;   # intermediate(s) + root

This clears the stapling warning because nginx now has the issuer available for lookup. It does not fix the handshake, because the served chain is still incomplete — so keep this as a compatibility shim, not a target state.

If outbound DNS from the nginx host is blocked or filtered, bypass resolution entirely with an explicit responder URL taken from step 3.4:

ssl_stapling_responder http://ocsp.example-ca.com;

Trade-off: you now own that URL. If the CA rotates responders, stapling silently stops working after the next renewal.

6. Comparison: Which Configuration Actually Clears the Warning?

Configuration Contents of the file(s) Clears the warning? Notes
Leaf only in ssl_certificate 1 certificate No Smallest handshake, but stapling is off and AIA-less clients fail
Full chain in ssl_certificate Leaf + intermediate(s) Yes Recommended baseline; fixes stapling and the served chain at once
Leaf in ssl_certificate + ssl_trusted_certificate Leaf, then intermediate(s) + root Yes Stapling works, served chain still incomplete — compatibility only
ssl_trusted_certificate with root only Root CA No The root is not the issuer of your leaf
ssl_stapling_responder + no resolver Leaf + intermediate(s) Yes Skips DNS; must be updated if the CA changes responder
ssl_stapling off; Any N/A Correct answer when the certificate has no OCSP URL

7. Prove the Staple Is Actually Being Sent

A clean error.log is necessary but not sufficient. Ask the server directly:

echo | openssl s_client -connect example.com:443 -servername example.com -status 2>/dev/null | grep -E 'OCSP Response Status|Cert Status|This Update|Next Update'

Healthy output:

OCSP Response Status: successful (0x0)
Cert Status: good
This Update: Jun  1 00:00:00 2025 GMT
Next Update: Jun  8 00:00:00 2025 GMT

If you instead see:

OCSP response: no response sent

…then nginx is still not stapling. Re-check error.log — the reason will be there, and section 8 maps each message to a cause.

Two gotchas when verifying:

  • First request after reload is often unstapled. nginx fetches the OCSP response asynchronously. Run the command twice, or wait a few seconds.
  • Watch the right log. Warnings are emitted at configuration load, not per request:
grep -i stapling /var/log/nginx/error.log | tail -20

No output means no stapling warnings — but confirm with nginx -t after a reload that the file has been rotated recently enough to include the current process start.

8. Troubleshooting: Real Messages and What They Mean

Message Cause Fix
nginx: [warn] "ssl_stapling" ignored, issuer certificate not found for certificate "/etc/nginx/ssl/example.com.crt" Leaf-only file; issuer not loaded Use fullchain in ssl_certificate, or add the intermediate to ssl_trusted_certificate
nginx: [warn] "ssl_stapling" ignored, no OCSP responder URL in the certificate "/etc/nginx/ssl/fullchain.pem" The certificate has no AIA OCSP URL — the CA does not run OCSP Set ssl_stapling off; and remove the warning noise
nginx: [warn] "ssl_stapling" ignored, host not found in OCSP responder "ocsp.example-ca.com" Missing resolver, or egress DNS/HTTP blocked Add resolver, allow outbound HTTP to the responder, or pin ssl_stapling_responder
OCSP response: no response sent (from s_client) Stapling disabled by a warning above, or the first request after reload Fix the log warning; retry the handshake
OCSP Response Status: tryLater (0x3) Responder overloaded or rate-limiting you Back off and retry; nginx refreshes periodically
verify error:num=20:unable to get local issuer certificate / Verify return code: 21 (unable to verify the first certificate) Server is not sending the intermediate Serve the full chain in ssl_certificate
nginx: [emerg] cannot load certificate "/etc/nginx/ssl/fullchain.pem" Concatenation broke the PEM (missing newline between blocks) or wrong path Re-concatenate with cat; confirm each block ends with -----END CERTIFICATE----- on its own line

One more non-obvious case: if ssl_stapling_verify on; is set but ssl_trusted_certificate is absent or lacks the root, nginx can fetch a response and still refuse to staple it because it cannot verify the signature. The log stays quiet about the chain in some builds, so if fetching works but nothing is stapled, add the full intermediate + root bundle.

9. FAQ

Do I still need ssl_trusted_certificate if ssl_certificate already has the full chain?
Not to clear the warning — nginx finds the issuer in the ssl_certificate chain. But with ssl_stapling_verify on you should still provide a bundle containing the intermediate(s) and the root, because verification needs a trust anchor.

Should the root certificate go in ssl_certificate?
No. Send the leaf plus intermediates only. The root is already in every client’s trust store; including it just bloats the handshake. Keep the root in ssl_trusted_certificate where it belongs.

Does order inside the file matter?
Yes. The leaf must be first in ssl_certificate. A chain file with the intermediate at the top is a classic cause of unable to get local issuer certificate even when the right certificates are present.

Why does the warning appear at startup rather than per request?
Chain resolution happens when the configuration is loaded, once per certificate. That is why nginx -s reload is required after every change, and why the message is timestamped at worker start.

Why is the first request after reload not stapled?
nginx fetches OCSP responses asynchronously so it never blocks a handshake on a CA. The first client may get an unstapled handshake; subsequent ones get the cached response.

Can nginx staple OCSP responses for intermediate certificates?
No. Only the leaf certificate configured in that server block is stapled. If you run an RSA and an ECDSA certificate side by side, each needs its own complete chain.

Is OCSP stapling still worth configuring?
It depends on your CA. Let’s Encrypt wound down its OCSP service in 2025, so newly issued certificates have no OCSP responder URL and produce the no OCSP responder URL warning no matter how perfect your chain is. Check with openssl x509 -noout -ocsp_uri: if it prints nothing, disable stapling and rely on the CA’s CRL or short-lived certificates instead.

Does stapling work if nginx sits behind a load balancer?
Only if nginx terminates TLS. If the balancer terminates TLS and passes plaintext HTTP to nginx, the balancer is responsible for stapling and nginx’s ssl_stapling directive is irrelevant.

Will nginx -t catch this?
Sometimes it prints the warning, but the authoritative place is error.log at startup and reload. Treat a clean nginx -t as necessary, not sufficient, and always confirm with openssl s_client -status.