OpenSSL "Verify return code: 21" (unable to verify the first certificate) in CI

By Kaveh Alemi·Latchkey

Return code 21 means OpenSSL could verify neither the leaf nor build a path, because the server presented the leaf certificate without the intermediate that chains it to a trusted root. The root is usually in the store; the missing link is the intermediate. The fix is to serve the full chain from the endpoint, or supply the intermediate to the client.

What this error means

openssl s_client ends with "Verify return code: 21 (unable to verify the first certificate)". Browsers that cache intermediates may still work, which masks the incomplete chain.

verify error:num=21:unable to verify the first certificate
Verify return code: 21 (unable to verify the first certificate)

Common causes

The server omits the intermediate certificate

The endpoint sends only the leaf. Without the intermediate, OpenSSL cannot chain it to the trusted root even though the root is present.

A misconfigured certificate bundle on the server

The deployed PEM includes only the leaf, or lists certificates in the wrong order, so the chain does not resolve.

How to fix it

Serve the full chain from the endpoint

1. Rebuild the server certificate file as leaf followed by intermediate(s).
2. Redeploy so the endpoint presents the complete chain.
3. Verify with s_client that the return code is now 0.

# server PEM order: leaf first, then intermediate(s)
cat leaf.crt intermediate.crt > fullchain.pem

Supply the intermediate to the client

When you cannot change the server, pass the missing intermediate to OpenSSL so it can complete the path.

openssl s_client -connect example.com:443 \
  -CAfile root.pem -untrusted intermediate.pem

How to prevent it

• Always deploy the full chain (leaf plus intermediates) on TLS endpoints.
• Validate new certificates with s_client before they reach CI.
• Keep intermediates current when a CA rotates them.

Frequently asked questions

Related guides

References

• GitHub Actions documentation