Helping you to solve some of the most common issues when setting up a custom domain.
Setting up a custom domain can occasionally run into obstacles. Below, we outline frequent problems encountered during this process and provide detailed solutions to each of them.
SSL error: an error occurred when provisioning your SSL certificate.
When a custom domain is set for your organization, collection, or space, we set up an SSL certificate on our end so that your documentation will load securely, over HTTPS.
This happens automatically when you set your custom domain — you do not need to purchase or configure an SSL certificate.
Occasionally errors occur at this stage, usually when the CNAME record for the custom domain hasn't propagated.
In these cases, we can recommend the following:
Check that your CNAME record is set up correctly.
Please review our page about configuring DNS to help you with this.
If the CNAME record is incorrect, we won't be able to configure the SSL certificate and complete the custom domain set-up.
Verify if the CNAME has propagated. You can try using a third-party DNS lookup tool, such as WhatsMyDNS, to find out what the servers believe to be correct for your correct CNAME record.
If you are using Cloudflare, please confirm that you don’t have the record proxied as explained here.
Domain already connected error: your subdomain is already configured for different content.
A custom domain assigned to an organization or site must be unique. Attempting to use the same custom domain in more than one location will result in an error.
If this happens, you can click the link within the error message to look at the content the custom domain is already connected to. This may help you to decide what to do next.
It’s also possible that you might not have access to the content — if that’s the case, contact the support team and they can help you with your next steps.
The solution to this error will always be one of two things, however:
Choose a different custom domain; or
Disconnect the custom domain from the content it is already connected to, then reconnect it to the new content.
The custom domain is set correctly, but is redirecting to a different custom domain.
This is an expected behaviour, that usually can be changed.
The common issue is that custom domains have been set in multiple locations for example organization and the site. When someone accesses the URL for an organization, they are taken straight to the organization’s default content. Likewise, when someone accesses the URL for a multi-variant site, they are taken straight to the multi-variant default site.
Example
docs.example.com is set as the custom domain for an organization
team.example.com is set as the custom domain for that organization’s default content.
In this case, the expected behaviour would be docs.example.com redirecting you to team.example.com.
This issue can be solved by changing the default content or by removing the organization domain and adding the domains at a space level or the other way around (removing the space domain, and maintaining the org domain)
This issue frequently occurs due to the confusion over the location of the domain.
Please ensure you checked where your domains are set up, and adjusted this to your requirement.
