Troubleshooting·7 min read·

Custom domain not connecting — Cloudflare for SaaS troubleshooting

Custom domain setup failures on VeloCMS almost always trace to one of four Cloudflare for SaaS configuration issues. Here's the diagnostic tree and the fix for each branch.

When a custom domain doesn't connect on VeloCMS, the failure is almost always in one of four places: the CNAME record isn't pointing to proxy.velocms.org, the custom hostname isn't provisioned in Cloudflare for SaaS, the SSL certificate is still provisioning (takes up to 15 minutes), or the reader's DNS resolver is caching a stale NXDOMAIN response.

Check 1 — Verify the CNAME record

The domain owner must add a CNAME record at www (or @ for apex domains, using CNAME flattening) pointing to proxy.velocms.org. Check this with dig www.yourdomain.com CNAME +short. The output should be proxy.velocms.org. If it shows your old hosting provider's address or nothing, the CNAME hasn't been created or hasn't propagated. DNS propagation takes anywhere from 5 minutes to 48 hours depending on the previous TTL value.

# Verify CNAME is pointing to VeloCMS:
dig www.yourdomain.com CNAME +short
# Expected output:
proxy.velocms.org.

# Check SSL certificate status:
curl -I https://www.yourdomain.com 2>&1 | head -20
# Expected: HTTP/2 200 with Cloudflare-branded cert

Check 2 — Is the custom hostname provisioned?

In VeloCMS Admin Settings Custom Domain, the status badge next to your domain shows Active, Pending, or Error. Pending means Cloudflare is still provisioning the custom hostname and SSL certificate — wait up to 15 minutes. Error means the provisioning API call failed, usually because the domain is already registered as a custom hostname in another Cloudflare zone.

Check 3 — The apex domain gotcha

Cloudflare for SaaS requires the domain to be proxied (orange cloud) in Cloudflare to issue an SSL certificate. If the user's domain is on Cloudflare DNS with the CNAME set to DNS-only (grey cloud), the SSL certificate provisioning will time out. The CNAME must be orange-clouded — proxied through Cloudflare — for the custom hostname SSL to work.

Apex domains (yourdomain.com, without www) on Cloudflare can use CNAME flattening — Cloudflare automatically resolves the CNAME at the apex and serves the IP. This is a Cloudflare-specific feature and only works when the domain's DNS is managed in Cloudflare.

Check 4 — DNS cache flush

After fixing the CNAME or SSL issue, the reader's browser may still see the old cached DNS response. Ask the reader to try a private browsing window or clear their DNS cache with sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder on macOS. For a quick external check, use nslookup or Google's DNS Checker tool to verify the CNAME is resolving globally.