Custom Domains
Troubleshoot TLS errors on a custom domain
Why TLS certificate issuance failed and the three fixes that resolve 95% of cases.
Updated 2026-05-09
If your custom domain is verified but visitors see a TLS warning ("certificate not trusted", "ERR_CERT_AUTHORITY_INVALID"), Caddy couldn't get a Let's Encrypt certificate. Here's how to fix it.
1. Check CAA records#
This is the #1 cause. Run:
dig CAA links.acme.com
If you see 0 issue "digicert.com" or any CA that isn't letsencrypt.org, Let's Encrypt is blocked and certificate issuance fails silently.
Fix: add 0 issue "letsencrypt.org" to your domain's CAA records. You can keep the existing CA for any other certificate use — CAA is additive.
Wait 1 hour for the CAA propagation to clear, then click Retry verification in the dashboard.
2. Check for Cloudflare proxy#
If your DNS provider is Cloudflare and the record's "proxy status" shows the orange cloud, Cloudflare is terminating TLS at its edge with its own certificate. That breaks Caddy's on-demand TLS handshake.
Fix: click the orange cloud to grey (DNS only). Cloudflare's CDN is incompatible with our edge — we already cache aggressively at the edge POP, so you're not losing anything.
If you absolutely need the Cloudflare proxy (e.g. WAF rules), Business plans support a custom-origin mode where you point Cloudflare at our edge IP and we accept the proxied connection. Email support to enable.
3. Check rate limits#
Let's Encrypt rate-limits to 50 certificates per registered domain per week. If you've added a lot of subdomains in a short window, you may hit this.
Fix: wait. We retry every 12 hours, and most rate-limit windows clear within 7 days. Already-issued certificates keep working — only new issuance is blocked.
You can confirm the rate-limit status by checking crt.sh for your domain's recent certificates.
Still broken?#
- Check our status page. Sometimes Let's Encrypt itself has an incident.
- The dashboard's domain detail page shows the most recent Caddy error message verbatim — paste that into chat and we'll diagnose together.
- For air-gapped environments, you can self-host Caddy with your own internal CA. The self-hosting guide covers the configuration changes.
Once it works#
Set yourself a reminder in 60 days to verify renewal succeeded. We email the workspace's billing contact when renewal succeeds (you can opt out under Settings → Notifications). If renewal fails, we email and fire a webhook so your alerting catches it.