Troubleshooting Custom Domain Connection Failures in GitBook

The Problem: Domain Connection Failures

When connecting a custom domain to GitBook, the most common failure is a "Not Connected" or "SSL Pending" status in the dashboard. This prevents users from accessing your documentation via your branded URL, often resulting in a 404 error or a browser security warning (SSL_ERROR_BAD_CERT_DOMAIN).

The core issue is usually a mismatch between the DNS records at your registrar and the validation requirements of GitBook's automated SSL provisioning system.

Quick Diagnostic Table

Symptom	Likely Cause	Primary Check
Browser shows "Site cannot be reached"	Missing or incorrect CNAME record	DNS Lookup (dig/nslookup)
Browser shows "Your connection is not private"	SSL Certificate pending or failed	GitBook Domain Settings status
DNS is correct, but status is still "Pending"	CAA record restriction or TTL lag	CAA Record check

Step-by-Step Resolution Path

1. Verify DNS Record Accuracy

GitBook requires a CNAME (Canonical Name) record to map your custom domain to their infrastructure. If this is missing or pointing to an old host, the site will not load.

Run the following command from your local terminal (replace docs.example.com with your actual domain):

dig CNAME docs.example.com

Expected Result: The ANSWER SECTION should show the domain pointing to gitbook.io or www.gitbook.io. If the answer is empty or points elsewhere, you must update your DNS records at your domain registrar.

2. Check SSL Provisioning and CAA Records

Once DNS is pointed correctly, GitBook attempts to issue an SSL certificate via Let's Encrypt. If this fails, the domain will remain in a "Pending" state.

• CAA Record Conflict: Check if your DNS has a CAA (Certification Authority Authorization) record. If a CAA record exists but does not explicitly allow letsencrypt.org, the certificate issuance will be blocked.
• Validation Lag: SSL provisioning can take up to 30 minutes after DNS propagation. Avoid clicking "Verify" repeatedly, as this can trigger rate limits on the certificate authority.

3. Validate GitBook Dashboard Configuration

Ensure the domain is explicitly added to the project settings. A DNS record alone is insufficient; GitBook must be expecting traffic for that specific hostname.

1. Navigate to Settings → Domain in your GitBook project.
2. Confirm the domain string matches exactly what you configured in your DNS (e.g., docs.example.com vs www.docs.example.com).
3. Verify the status has transitioned from "Pending" to "Connected".

Comparison: CNAME vs. A Records

GitBook specifically recommends CNAME records for custom domains. Using an A record (pointing to a static IP) is generally discouraged because GitBook may change their infrastructure IPs, which would cause an immediate outage for your site.

Feature	CNAME (Recommended)	A Record (Not Recommended)
Target	Hostname (gitbook.io)	IP Address
Maintenance	Automatic (handled by GitBook)	Manual (requires update on IP change)
SSL Setup	Seamless integration	Potential validation delays

Verification and Testing

To confirm the fix is live and not cached by your browser, use curl to check the HTTP response headers:

curl -I https://docs.example.com

Expected Result: A HTTP/2 200 response. If you see a 404 or a SSL handshake error, the configuration is still incorrect.

Rollback Procedure

If the custom domain configuration causes unexpected outages for other subdomains or email services (common when misconfiguring the root domain), revert the DNS changes:

1. Log into your DNS provider.
2. Delete the CNAME record created for GitBook.
3. Restore the previous CNAME or A record that was in place prior to the change.
4. Wait for the TTL (Time to Live) period to expire for the change to propagate.

Escalation Criteria

Contact GitBook support if the following conditions are met:

• dig confirms the CNAME points to gitbook.io.
• No CAA records are blocking Let's Encrypt.
• The status in the GitBook dashboard remains "Pending" or "Failed" for more than 2 hours.