From 089adfd21eaa49071b45b03346d51a4829d01f71 Mon Sep 17 00:00:00 2001 From: Alejandro Cortez Date: Thu, 11 Jun 2026 12:15:15 -0400 Subject: [PATCH 1/2] Document custom hostname setup for Cloudflare-proxied domains TXT pre-validation cannot complete while a domain is proxied through Cloudflare, even when the records resolve correctly. Add a section with the setup order for proxied domains and link it from the warning. Co-Authored-By: Claude Fable 5 --- customize/custom-domain.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/customize/custom-domain.mdx b/customize/custom-domain.mdx index d54a840379..e25b857c7b 100644 --- a/customize/custom-domain.mdx +++ b/customize/custom-domain.mdx @@ -49,6 +49,8 @@ CNAME | docs | cname.mintlify.builders Do not add or change your `CNAME` until both verification `TXT` records show as verified in your dashboard. Each appears with a green check when DNS is correct. The dashboard verifies `TXT` records before certificate provisioning can complete. Switching `CNAME` too early commonly breaks HTTPS until provisioning finishes. If you migrate an existing domain and want zero downtime, publish the verification `TXT` records first and wait until they show verified and TLS has pre-provisioned before pointing `CNAME` at Mintlify. + + This pre-validation flow does not work for domains proxied through Cloudflare. See [Cloudflare-proxied domains](#cloudflare-proxied-domains). ### Verification TXT records @@ -88,6 +90,18 @@ If your domain uses CAA (Certification Authority Authorization) records, you mus Mintlify reserves the `/.well-known/acme-challenge` path for certificate validation. You cannot redirect or rewrite this path. If you have configured redirects or rewrites for this path, certificate provisioning fails. +### Cloudflare-proxied domains + +If your domain is already proxied through Cloudflare (the proxy status shows an orange cloud), the verification `TXT` records cannot show as verified before you update your `CNAME`. This happens even when the records resolve correctly with tools like `dig` or DNSChecker. Cloudflare's proxy prevents the verification from completing until traffic for the hostname routes to Mintlify. + +For Cloudflare-proxied domains, follow this order instead: + +1. Add the verification `TXT` records at your DNS provider. +2. Update your `CNAME` record to point to `cname.mintlify.builders` without waiting for the `TXT` records to show as verified. +3. Wait for verification and TLS provisioning to complete. Your site may briefly serve an invalid certificate during provisioning. + +If you need zero downtime during migration, set the `CNAME` record's proxy status to **DNS only** (gray cloud) instead. This allows the standard pre-validation flow to complete before you switch traffic. + ### Provider-specific settings From e1a45fad8097e6883fdfd3908f3cd4a8a788960a Mon Sep 17 00:00:00 2001 From: Alejandro Cortez Date: Thu, 11 Jun 2026 12:56:14 -0400 Subject: [PATCH 2/2] Update customize/custom-domain.mdx Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> --- customize/custom-domain.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/customize/custom-domain.mdx b/customize/custom-domain.mdx index e25b857c7b..eb5c05a2dd 100644 --- a/customize/custom-domain.mdx +++ b/customize/custom-domain.mdx @@ -94,7 +94,7 @@ Mintlify reserves the `/.well-known/acme-challenge` path for certificate validat If your domain is already proxied through Cloudflare (the proxy status shows an orange cloud), the verification `TXT` records cannot show as verified before you update your `CNAME`. This happens even when the records resolve correctly with tools like `dig` or DNSChecker. Cloudflare's proxy prevents the verification from completing until traffic for the hostname routes to Mintlify. -For Cloudflare-proxied domains, follow this order instead: +For Cloudflare-proxied domains, follow these steps: 1. Add the verification `TXT` records at your DNS provider. 2. Update your `CNAME` record to point to `cname.mintlify.builders` without waiting for the `TXT` records to show as verified.