Troubleshooting·7 min read·

My custom domain SSL isn't working

Custom domain SSL errors usually come from DNS: a proxied record, a CNAME that doesn't match your panel, a missing TXT, or a CAA blocking Let's Encrypt.

You added your custom domain in Admin → Settings → Branding → Custom Domain and pointed your DNS at VeloCMS, but now your browser shows a certificate error, an insecure connection warning, or the domain just doesn't resolve at all. The panel shows the state of the connection as a status next to your domain — Pending DNS, Verifying, Active, or Failed — and each one points at a different fix.

The single most important thing to check first

Look at the records the panel shows for your domain. VeloCMS gives every custom domain its own CNAME target (a unique address, not a shared one) plus a TXT record that proves you own the domain. Both must exist in your DNS, exactly as shown, before a certificate can be issued. If you use Cloudflare, the CNAME must be set to DNS only (the grey cloud, not the orange proxied cloud): a proxied record answers with Cloudflare's own addresses instead of your target, so VeloCMS cannot see that your domain points at it and verification stalls.

Grey cloud (DNS only) is required for VeloCMS custom domains. An orange-cloud (proxied) record hides the CNAME target, so the domain never verifies and no certificate is issued. This is the cause of most custom domain SSL failures we see.

Step 1 — Check your DNS records

  • Open Admin → Settings → Branding → Custom Domain and copy the CNAME target and the TXT record (name and value) shown for your domain. They are unique to your domain, so don't reuse values from another domain or an older setup.
  • In your DNS provider, make sure the CNAME record for your domain points to exactly that target and the TXT record exists with the exact name and value shown. If your CNAME still points at proxy.velocms.org from an earlier setup, replace it with the target shown in the panel.
  • If you use Cloudflare, click the orange cloud beside the CNAME so it turns grey (DNS only).
  • Other DNS providers (Namecheap, GoDaddy, and so on) have no proxy toggle, so just check the values. If your domain is a root domain (example.com) and your provider can't put a CNAME on the root, follow the root-domain option the panel shows.
  • Save the changes, then click Check DNS records in the panel: each record shows Matched, Mismatch, or Missing, so you can see what still needs fixing.
  • Wait a few minutes for DNS to propagate.

Step 2 — Trigger verification

After your DNS records are correct, go back to Admin → Settings → Branding → Custom Domain and click Verify Now. VeloCMS re-checks your DNS; once it matches, the status moves from Pending DNS to Verifying while your SSL certificate is issued, then to Active. Issuing usually takes 5–15 minutes after DNS verifies. If the status is still Pending DNS or Verifying after 30 minutes, work through the sections below; if it changes to Failed, see the last section.

CAA records blocking certificate issuance

CAA (Certification Authority Authorization) records tell certificate authorities which CAs are allowed to issue certificates for your domain. VeloCMS certificates are issued by Let's Encrypt, so if your domain has a CAA record that doesn't include letsencrypt.org, issuance is blocked and the status stays stuck on Verifying (the panel may also show a domain issue banner).

# Check for CAA records on your domain
dig CAA yourdomain.com

# If you see CAA records, add one that permits Let's Encrypt:
# yourdomain.com. 300 IN CAA 0 issue "letsencrypt.org"

If you have CAA records and none of them includes letsencrypt.org, add one. You can have multiple CAA records — adding letsencrypt.org doesn't remove the others. If you have no CAA records at all, you're fine — the absence of CAA records means all CAs are permitted.

Certificate shows as active but browser still shows error

If Admin shows the certificate as Active but your browser still shows an error, the issue is usually a cached bad cert in your browser. Try the domain in an incognito window or a different browser. Also try clearing your browser's SSL state — in Chrome, this is at chrome://settings/security → Manage device certificates. On macOS, you may also need to flush the system DNS cache.

If you changed your DNS from pointing to another host to VeloCMS, your readers' browsers may have cached the old certificate for up to 24 hours. This resolves on its own — it is browser-side cache, not DNS cache.

Domain shows the wrong site

If your custom domain resolves but shows the VeloCMS landing page instead of your blog, the domain verification step wasn't completed inside VeloCMS admin. Go to Admin → Settings → Branding → Custom domain, confirm the domain is listed there, and that the status shows Active. If the domain isn't listed at all, add it and complete the verification flow before your DNS change takes effect.

The status shows Failed

Failed means DNS verification or certificate issuance failed outright, and the panel shows the error. The fastest recovery is to click Disconnect and add the domain again. This registers it afresh and restarts verification and certificate issuance from scratch. After re-adding, compare the CNAME target and TXT record the panel shows with what is in your DNS and update them if they differ. Your blog content and subscribers are not affected, and your blog stays reachable at its velocms.org address in the meantime. If it fails again, contact support from the Help menu with the domain name and the error shown next to Failed.