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 atssl_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:
- At startup/reload, Nginx builds the chain and locates the issuer.
- It reads the OCSP URL from the leaf and resolves the hostname using
resolver. - It fetches and caches the signed OCSP response, refreshing before
Next Update. - On each handshake it attaches the cached response to the certificate status message.
Step 1 is the one failing.
3. Fix #1 (Recommended): Put the Full Chain in ssl_certificate
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
serverblock. 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.