Setting up a custom domain
A site can carry one custom domain. Setting it up walks through four stages, and the product shows you exactly which DNS record it wants at each one.
The first record is genuinely optional. The second is not, and it is where most setups stall.
#The four stages
Stage | What you add | Status shown |
|---|---|---|
Stage 1, Claim | TXT at _capable-verify.{your domain}, with a random 12-character value | "Continue setup" |
Stage 2, Certificate | A CNAME shown on the card under "DNS Validation Required", with copyable Name and Value | "Validating..." |
Stage 3, CDN | None from you yet, the CDN is being built | "Setting up CDN..." |
Stage 4, Traffic | A CNAME from your domain to the CloudFront hostname shown under "DNS Configuration" | "Active" |
#What each stage means
#Stage 1, Claim
The claim expires after 48 hours; the card shows "Claim expires at: {date}". After that, Continue setup returns "Domain claim has expired. Start setup again."
#Stage 2, Certificate
Without a certificate, nothing progresses. The system checks every 5 minutes for up to 48 hours, then fails with "Certificate validation timed out. Ensure the DNS CNAME record is correctly configured."
#Stage 3, CDN
Takes up to 20 minutes.
#Stage 4, Traffic
Once Active, the site URL shown throughout the product (settings header, overview, catalogue, share cards) switches to your custom domain. That value is cached for up to 60 seconds.
#Failure, Domain is already in use on another CloudFront distribution
Each domain can only be attached to one CloudFront distribution worldwide. Remediation shown: find the other distribution in every AWS account you own, remove the alias or delete the distribution, wait about 5 minutes, then Retry. This is the most common failure.
#Failure, CloudFront CNAME limit reached
Not retryable in-product; the card says to contact support to raise the quota or free a distribution.
#Failure, DNS validation did not complete in time
The validation CNAME was never seen within 48 hours. Check it is present, is not behind a CDN or proxy, then Retry.
#Failure, Certificate request failed / Certificate is not valid for this domain
Check the domain resolves publicly, then Remove and re-add the domain to request a fresh certificate. Retry will not help here.
#Failure, Could not create the CDN distribution / edge function / storage access control / incomplete response
All retryable from the card. Any partially created resources are cleaned up first.
#Rejected, Invalid format
"Use lowercase letters, numbers, and hyphens only. It must start and end with a letter or number."
#Rejected, Domain not allowed
Reserved and infrastructure suffixes are not allowed.
#Rejected, Platform domain
"You cannot register a domain that matches or is part of the Capable Sites hosting domain."
#Rejected, Possible impersonation or phishing / Recognized brand or trademark / Misleading name / Offensive language
An automated AI review of the requested name. The first three offer a "Contact support for a review" button linking to https://help.gocapable.com/confluence-sites.
#Rejected, Safety check unavailable
"We could not complete our automated safety review right now. Please try again in a few minutes." The check fails closed on timeout or error, so this can happen for reasons outside your control.
#Rejected, Domain is already registered (409)
Including a domain still attached to another of your own sites, or to a site you deleted (see caveats).
#Security
The certificate and CDN run with TLS 1.2 minimum, HTTP/2 and HTTP/3, and all plain HTTP traffic is redirected to HTTPS. Custom-domain sites get the same web application firewall as the shared address.
#A few things worth knowing
One custom domain per site. The Add button disappears once you have one.
The claim TXT record expires after 48 hours, and setup has to be restarted after that.
An apex domain needs a DNS provider that supports flattening or ALIAS records. See the troubleshooting page.
#Related
Two records. One of them matters.
