ReadTheDocs custom domains vs. Let's Encrypt validation: which failure class does the dashboard surface?

Answer

The dashboard does not reliably distinguish DNS propagation lag, CAA blocking, Let's Encrypt rate limits, or record misconfiguration. In current ReadTheDocs custom-domain flows those failures are collapsed into a single generic validation or provisioning failure/pending state. Operators cannot tell from the UI alone whether to wait, fix CAA, back off retries, or correct DNS records.

Confirmed facts

• Let's Encrypt issuance for a ReadTheDocs custom domain is gated on the hostname resolving to ReadTheDocs serving infrastructure.
• Apex domains use A records (or provider ALIAS/ANAME flattening); subdomains use CNAME.
• CAA records, when present, must permit letsencrypt.org; absence of CAA is not a block, only restrictive CAA is.
• Dashboard status taxonomy and wording vary by ReadTheDocs deployment and version, so this behavior must be verified in your instance before writing a runbook.

Likely explanation

Because ACME validation failures are collapsed into one domain state, transient DNS propagation, wrong record sets, CAA denial, and Let's Encrypt rate limits look identical to the operator. Renewal inherits the same ambiguity: a domain repointed after initial success loses HTTPS with no actionable signal.

Recommended exposure order

1. Expose the DNS precondition first: does the name resolve, and does it match the expected ReadTheDocs target? This separates transient propagation from record misconfiguration.
2. Expose CAA as a distinct deterministic block when DNS is correct but issuance is denied; waiting or retrying will not help.
3. Expose Let's Encrypt rate limits only after DNS and CAA are confirmed, as a time-bound back-off signal.

Verification steps (safe, scoped)

1. On a non-production custom domain, leave DNS unset and capture the exact dashboard status text and timestamp.
2. Set only a blocking CAA record and repeat; note whether the message changes.
3. Run dig +trace A example.com for an apex or dig +trace CNAME sub.example.com for a subdomain, and compare against the target ReadTheDocs expects.
4. Run dig CAA example.com and confirm any issue entries include letsencrypt.org.
5. After DNS and CAA are confirmed good, trigger one validation and inspect available domain or validation logs for ACME detail. Do not repeatedly retry a generic failure; attempts can consume Let's Encrypt rate limits.

Assumptions and uncertainty

This draft assumes a standard ReadTheDocs custom-domain provisioning path. The exact dashboard labels and whether any subclassification exists depend on your deployment and version, which I have not verified. Treat the generic-state conclusion as unconfirmed until you capture the actual status text in your instance.

Missing diagnostic detail: what exact status text does your dashboard show for the failing domain? That determines whether the generic-state finding applies to your instance.