跳到主要内容

Nginx: ssl_stapling ignored, issuer certificate not found

You turned on OCSP stapling, reloaded Nginx, and got a warning instead of a working feature: "ssl_stapling" ignored, issuer certificate not found. The site still serves HTTPS, so it is tempting to ignore — but every client is now doing its own OCSP lookup (or skipping it), which costs latency and privacy. This guide explains why Nginx cannot find the issuer, the two-file fix, how to prove stapling actually works, and what to do when the warning changes into a different error.

1. What the Warning Actually Says

The message is emitted at configuration load or reload, not at request time:

2025/03/04 10:12:41 [warn] 2143#2143: "ssl_stapling" ignored, issuer certificate not found for certificate "/etc/nginx/ssl/example.com.crt"

Read it literally. Nginx parsed ssl_stapling on;, opened the file referenced by ssl_certificate, and tried to locate the certificate that issued the leaf certificate inside that same file. It found only the leaf, so it gave up and disabled stapling for that server block.

Two things worth noting before you change anything:

  • It is a warning, not an error. TLS keeps working; only the stapled OCSP response is missing.
  • The path in the message is the diagnosis. It points at ssl_certificate, not at ssl_trusted_certificate. That is the file Nginx scans for the issuer chain.

2. Why Nginx Needs the Issuer Certificate at All

An OCSP request must be signed. Per RFC 6960, the request is signed either by the CA that issued the certificate being checked, or by a delegated responder explicitly named in the certificate’s Authority Information Access (AIA) extension. To build and sign that request, Nginx needs the issuer’s public key material, which means it needs the intermediate certificate that signed your leaf.

The chain looks like this:

Root CA (in client trust stores, not sent by you)
  └── Intermediate CA  <-- Nginx must find this
        └── example.com leaf  <-- what ssl_certificate usually contains today

Nginx resolves the issuer by walking the certificate list inside ssl_certificate. If that file holds a single PEM block, there is nothing to walk. The OCSP responder URL itself comes from the leaf’s AIA extension, so a certificate with no OCSP URL fails differently — see the troubleshooting table in section 6.

The full stapling lifecycle is:

  1. At startup/reload, Nginx builds the chain and locates the issuer.
  2. It reads the OCSP URL from the leaf and resolves the hostname using resolver.
  3. It fetches and caches the signed OCSP response, refreshing before Next Update.
  4. On each handshake it attaches the cached response to the certificate status message.

Step 1 is the one failing.

Concatenate leaf plus intermediate, in that order, and point ssl_certificate at the result. If your CA already gives you a bundle (Let’s Encrypt’s fullchain.pem, DigiCert’s fullchain.crt), use it as-is.

cd /etc/nginx/ssl
cat example.com.crt intermediate.crt > fullchain.pem

# Confirm the leaf is first and the chain verifies
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
openssl verify -untrusted intermediate.crt example.com.crt

The expected verification output is a single line: example.com.crt: OK. Then update the 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_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/nginx/ssl/chain.pem;

    resolver 1.1.1.1 8.8.8.8 valid=300s;
    resolver_timeout 5s;
}
nginx -t && nginx -s reload
tail -n 30 /var/log/nginx/error.log

Order matters: leaf first, then intermediates. Reversing the order produces handshake failures on some clients even though nginx -t passes. Do not put the root certificate in ssl_certificate — it is already in client trust stores and only bloats the handshake.

4. Fix #2: ssl_trusted_certificate, and How the Directives Differ

A common misconception: adding ssl_trusted_certificate alone will silence the issuer certificate not found warning. In current Nginx it usually will not, because the issuer lookup happens against the ssl_certificate chain. ssl_trusted_certificate has a different job — it supplies the trust anchors used to verify the signature on the OCSP response when ssl_stapling_verify on; is set. Use both: fullchain for chain building, trusted file for response verification.

Directive What it does File must contain Fixes “issuer certificate not found”?
ssl_certificate Certificate chain presented to clients Leaf first, then intermediates Yes — this is the fix
ssl_certificate_key Private key for the leaf Key only, mode 600 No
ssl_trusted_certificate Verifies the OCSP response signature Intermediates + root No (most builds)
ssl_stapling Enables stapling for the server block on / off —
ssl_stapling_verify Rejects responses that fail verification on / off —
resolver Resolves the OCSP responder hostname at runtime One or more DNS IPs No, but required at runtime

If you are unsure which file is which on a Certbot install, the paths are predictable:

ls -l /etc/letsencrypt/live/example.com/
# fullchain.pem -> ssl_certificate
# privkey.pem   -> ssl_certificate_key
# chain.pem     -> ssl_trusted_certificate

5. Verify: Reload, Read the Log, Then Ask the Server

Three checks, in this order. Do not trust the absence of a warning alone.

# 1. Config is valid and the warning is gone
nginx -t
tail -n 50 /var/log/nginx/error.log | grep -i stapling

# 2. The server actually sends a stapled response
openssl s_client -connect example.com:443 -servername example.com -status </dev/null 2>/dev/null 
  | grep -A6 "OCSP Response"

A healthy result looks like this:

OCSP Response Status: successful (0x0)
Response Type: Basic OCSP Response
Responder Id: C = US, O = Let's Encrypt, CN = R3
This Update: Mar  4 09:00:00 2025 GMT
Next Update: Mar 11 09:00:00 2025 GMT

Confirm the chain is being served, not just the leaf:

openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null 
  | grep -c "BEGIN CERTIFICATE"
# expect 2 (leaf + intermediate) or 3 if you include the root

And test the responder directly, bypassing Nginx, to separate a CA-side problem from a config problem:

openssl x509 -in /etc/nginx/ssl/fullchain.pem -noout -ocsp_uri
openssl ocsp -issuer /etc/nginx/ssl/chain.pem -cert /etc/nginx/ssl/fullchain.pem 
  -url "$(openssl x509 -in /etc/nginx/ssl/fullchain.pem -noout -ocsp_uri)" -resp_text -noverify

Timing caveat: right after a reload, the first request often shows OCSP response: no response sent. Nginx fetches the response asynchronously and caches it per worker. Wait a few seconds, reconnect, and check again before you start debugging.

6. Troubleshooting: Real Messages and What They Mean

Message (error.log or s_client) Cause Fix
"ssl_stapling" ignored, issuer certificate not found for certificate "..." Intermediate missing from ssl_certificate Serve fullchain (section 3)
"ssl_stapling" ignored, no OCSP responder URL in the certificate CA does not run OCSP; the leaf has no AIA OCSP entry. Let’s Encrypt stopped OCSP in 2025 Nothing to fix — remove ssl_stapling or accept the warning
no resolver defined to resolve "ocsp.example-ca.com" No resolver directive in the http or server block Add resolver 1.1.1.1 8.8.8.8 valid=300s;
OCSP responder "ocsp.example-ca.com" timed out Outbound DNS/HTTP blocked by firewall, or resolver unreachable Allow outbound 53/80/443, switch resolver, raise resolver_timeout
OCSP_basic_verify() failed Response signature cannot be verified against ssl_trusted_certificate Rebuild chain.pem with intermediates + root; check for an expired intermediate
OCSP response: no response sent (s_client) Stapling disabled, not yet fetched, or cache empty Reconnect after a few seconds; re-check the log for a warning
verify error:num=20:unable to get local issuer certificate (client side) Server sends leaf only Same fullchain fix; unrelated to stapling but shows up in the same tests
OCSP Response Status: tryLater (3) Responder busy or rate-limiting your IP Retry later; reduce reload frequency; Nginx will keep the cached response

One more trap: if the certificate carries the OCSP Must-Staple extension and stapling is broken, modern clients will hard-fail the connection. Check with openssl x509 -in fullchain.pem -noout -text | grep -i "must staple". If it is present and you cannot keep stapling reliable, reissue without Must-Staple rather than shipping a time bomb.

7. Automation and Hardening Notes

Stapling breaks most often after a renewal, when a new intermediate appears and the old concatenated file is stale. Eliminate the manual step:

# Certbot already writes a correct fullchain.pem — reference it directly
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;

# Reload only after a successful validation
certbot renew --deploy-hook "nginx -t && systemctl reload nginx"

For monitoring, a one-line cron or Prometheus textfile check is enough:

openssl s_client -connect example.com:443 -servername example.com -status </dev/null 2>/dev/null 
  | grep -q "OCSP Response Status: successful" || echo "OCSP STAPLING DOWN on example.com"

Other settings worth knowing:

  • ssl_stapling_responder http://ocsp.example-ca.com; overrides the URL from the certificate — useful when the AIA points at a host your network cannot reach.
  • Nginx refreshes the cached response automatically before Next Update; there is no cache size to tune.
  • Stapling is configured per server block. A second vhost with the same certificate needs its own directives.
  • Keep ssl_stapling_verify on; in production — without it you staple whatever the responder returns, unverified.

8. FAQ

Q: Is the warning dangerous?
A: Not by itself. TLS works; clients just lose the stapling optimization. It becomes dangerous only if the certificate has Must-Staple, which turns a soft failure into a hard connection failure.

Q: Can I just delete ssl_stapling on;?
A: Yes, and with OCSP being phased out by several CAs that is increasingly the correct answer. Removing the directive removes the warning and the async fetches. Check -ocsp_uri first — if it prints nothing, there is nothing to staple.

Q: Why does ssl_trusted_certificate not fix the warning?
A: Because Nginx looks for the issuer inside the ssl_certificate chain. The trusted file is consumed later, when verifying the OCSP response signature. Add it anyway when ssl_stapling_verify on; is set.

Q: Does the file order really matter?
A: Yes. Leaf first, then intermediates, root last or omitted. Nginx will start with the wrong order but clients that build chains strictly will reject the handshake.

Q: Do I need the root certificate in the chain file?
A: No for ssl_certificate — clients already have it. For ssl_trusted_certificate, including the root makes OCSP response verification more robust, especially with older OpenSSL builds.

Q: It worked yesterday and now says “no OCSP responder URL in the certificate”. What changed?
A: The certificate was renewed by a CA that no longer runs OCSP (Let’s Encrypt ended its OCSP service in 2025). Nothing in your config broke; the feature no longer applies to that certificate.

Q: Why is s_client still reporting “no response sent” after the fix?
A: The fetch is asynchronous. Reload, wait 5–10 seconds, and reconnect. If it persists, check error.log for a resolver or timeout message — Nginx never reached the responder.

Q: Does this apply to stream blocks?
A: Only on recent Nginx versions that expose stapling for the stream SSL module, and the same chain rules apply. On older builds, stapling is HTTP-only.