Certificates: failures, renewal, handshakes
Certificate order states, failure types and fixes, which failures retry, when renewal starts, and how nodes pick a certificate during the TLS handshake.
Order states
Issuance and renewal progress is on the "Certificate orders and renewal status" page (your control plane address followed by /dashboard/site/cert/orders); see Enable HTTPS.
| State | Meaning |
|---|---|
| Pending | The order exists and waits for the issuance service |
| Validating | Validation records are being written and the CA is validating the domain |
| Issuing | The domain is validated and the certificate is being issued |
| Issued | The certificate was received and waits to be delivered |
| Deploying | Being delivered to nodes |
| Active | Nodes use this certificate |
| Renewal due | Renewal time has come; waiting to renew |
| Failed | The request failed; the failure column shows the type and the CA's own text |
| Revoked | The certificate was revoked |
Failure types
The failure column shows the type first; expand it for the text the CA returned.
| Type | Typical reasons | What to do | Retries |
|---|---|---|---|
| DNS validation | The TXT record is not live on every authoritative DNS server yet; DNS propagation timed out; the DNS provider rejected the credentials; the DNS API is unavailable | Check the DNS API credentials and permissions, and that this provider is the domain's authoritative DNS | Yes |
| No DNS zone | The selected DNS API hosts no zone for the domain | Use the DNS API that hosts the domain, or file validation | No |
| File validation (HTTP-01) | Some nodes are too old for file validation; the domain is not an active site or its line group has no serving node | Upgrade nodes, make sure the site is published to online nodes, or use DNS validation | No |
| Writing the record failed | Writing the DNS TXT record or the node validation file failed | Usually recovers; if it persists, check the DNS API or the nodes | Yes |
| Rejected by the CA | The CA could not validate the domain; the CA rejected the order | Expand the CA's text and act on it | No |
| EAB required | The CA requires EAB credentials | An administrator sets EAB under System settings → Website defaults → Certificate, or switch to Let's Encrypt | No |
| Rate limited or unreachable | Issuance was rate limited; the CA cannot be reached; the CA account is unavailable | Wait for the automatic retry; do not request again and again by hand | Yes |
| Finalizing and saving | Finalizing failed; the issued certificate failed validation; saving it failed | Wait for the automatic retry; contact the administrator if it persists | Yes |
| Interrupted | Timed out; processing was interrupted; the order is already being processed | Wait for the automatic retry | Yes |
Retried failures are tried up to 10 times, the interval starting at 1 minute and doubling up to 1 hour. A failure that is not retried would only fail the same way again: fix the cause first, then request again.
Renewal
- Certificates with automatic renewal start renewing 30 days before they expire. Each certificate adds a random offset of up to 24 hours, so certificates expiring the same day do not all renew at once.
- A failed renewal retries, the interval starting at 1 minute and doubling up to 1 hour, and never more than a quarter of the remaining validity.
- A failed renewal is sent to the notification center (to members subscribed to certificate notices); expiry reminders go out on the notice days the platform sets.
- The old certificate stays in use until the new one is active. When a certificate is about to expire, check the renewal first and do not unbind the old one.
How nodes pick a certificate
- Each site binds one certificate. It must cover every domain of the site, or the binding is refused; nodes never choose between several certificates themselves.
- A wildcard certificate
*.example.comcovers one level of subdomains and notexample.comitself. If the site also uses the bare domain, the certificate must include it. - In the handshake the node finds the site by SNI (the name the client sends in the handshake) and takes its certificate. In these cases the node refuses the handshake instead of sending a certificate that does not match: no SNI was sent; the SNI is no site's domain; the site has no HTTPS on this port; the certificate is missing, not yet valid or expired.
- Old clients that send no SNI therefore cannot open HTTPS sites.
- After the handshake the site is chosen by the request's Host. Only when an HTTP/2 or HTTP/3 connection is reused for another site with different TLS settings does the node answer 421, and the browser opens a new connection for that name.
- After a certificate change, new connections use the new certificate at once; established connections are not affected. TLS sessions never resume across sites.
Common questions
The browser says the certificate does not match the domain
Check that the site's certificate covers the domain you open (especially the bare domain and deeper subdomains), and that the site is published to the node you reach.
Checking the certificate a node sends with openssl
openssl s_client -connect www.example.com:443 -servername www.example.com -showcerts </dev/nullIf Certificate chain in the output lists only one certificate, the uploaded certificate lacks its intermediate: upload the full chain. Without -servername the handshake fails, because nodes refuse connections without SNI.
The order stays in validating
DNS validation waits until the TXT record is live on every authoritative server; file validation needs the domain to resolve to nodes and the site to be published. Once the retries run out the order fails, and the failure column says which step it stopped at.