Troubleshooting custom domains
GitHub Pages is available in public repositories with GitHub Free, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see "GitHub's products."
If your GitHub Pages site isn't loading at your custom domain or HTTPS isn't working, you can troubleshoot by reviewing common setup and configuration problems.
Tip: If you've recently changed or removed your custom domain and can't access the new URL in your browser, you may need to clear your browser's cache to reach the new custom domain. For more information on clearing your cache, see your browser's help site.
In this guide:
- GitHub repository setup errors
- DNS configuration errors
- Unsupported custom domain name
- HTTPS errors
- URL formatting error on Linux
GitHub repository setup errors
Tip: Custom domains are stored in a CNAME file in the root of your repository. You can add or update your custom domain through your repository settings. You can also edit the file directly to update your custom domain, although we recommend the procedure in "Adding or removing a custom domain for your GitHub Pages site."
The CNAME file isn't properly formatted
- The CNAME filename must be uppercase
- Only the bare domain or subdomain should be listed, e.g.,
For more information on setting up your custom domain, see "Adding or removing a custom domain for your GitHub Pages site."
Multiple domains in CNAME file
A CNAME file can contain only one domain. To point multiple domains to the same Page, set up redirects through your DNS provider.
CNAME already taken
If your custom domain is already used by another GitHub Pages site, you will receive a page build warning. When you add or edit your custom domain in your GitHub Pages site's repository settings, we automatically create a CNAME file in the root of your repository. A custom domain in a CNAME file can only be used once. Here are some examples of when you'll receive a page build warning for a duplicate custom domain:
If you have an apex domain such as
example.comin your CNAME file, this means that either
www.example.com) has been used in a CNAME file in another repository and is being used by the corresponding GitHub Pages site.
Likewise, if you have a
wwwsubdomain such as
www.example.comin your CNAME file, this means that either
www.example.comor its apex domain (
example.com) has been used in a CNAME file in another repository and is being used by the corresponding GitHub Pages site.
If you own the other GitHub Pages repository that is using your custom domain in its CNAME file, then you must remove the custom domain from your other repository's CNAME file before you can use it in a different pages site repository.
To remove the custom domain from a different GitHub Pages site repository you own, you can add a different custom domain to your GitHub Pages site or just remove your old custom domain.
If you don't own the repository that contains the CNAME file with your custom domain, try to contact the owner and ask them to update their custom domain. If you're unsure which repository contains the CNAME file with your custom domain, contact GitHub Support or GitHub Premium Support.
Reached limit for User or Organization pages site
You can only create one User or Organization pages site per GitHub account. For instance, there can only be one Organization pages site per organization account. Likewise, there can only be one User pages site per individual user account. Project pages sites are unlimited.
DNS configuration errors
Tip: If you have trouble pointing your GitHub Pages default domain to your custom domain, then contact your DNS provider for help. They can help confirm that you have configured your custom domain correctly.
DNS record doesn't point to GitHub's server
In order to serve the Page, your DNS records must point to GitHub's server. To confirm that your custom domain points to GitHub's servers, use the dig command with your custom domain. The dig command shows you where your custom domain points. For example:
$ dig example.com +nostats +nocomments +nocmd example.com. 3600 IN A 126.96.36.199
In the example above,
example.com points to the IP address
If you configured
A records through your DNS provider, your
A records must point your custom domain to the following IP addresses:
- You may see a different IP address, since we serve Pages with a global Content Delivery Network. Use
dig username.github.ioto see the full resolution path. Note that DNS caching may cause a delay.
- If you're using an
Arecord that points to
188.8.131.52, you'll need to update your DNS settings for your site to be available over HTTPS or served with a Content Delivery Network. For more information, see "HTTPS errors."
- If you're using an
Arecord that points to
184.108.40.206, you'll need to update your DNS settings, as we no longer serve Pages directly from those servers.
If you configured
CNAME records through your DNS provider, then your DNS record should point to your GitHub Pages default domain, such as
YOUR-GITHUB-USERNAME.github.io. Your default GitHub Pages domain is determined by the type of pages site you have. For examples, see this domain chart.
If you need help creating these records, contact your DNS provider as they should have the most detailed instructions. For some guidelines on configuring a DNS record with DNS providers, see "Using a custom domain with GitHub Pages."
Unsupported custom domain name
If your custom domain is unsupported then you may need to change your custom domain. You can also contact your DNS provider to see if they offer domain name forwarding services to redirect your site to an unsupported custom domain.
Unsupported custom domains include:
- using more than one apex domain (
- using more than one www subdomain (
- combination of an apex domain and custom subdomain (
Danger: Do not use wildcard DNS records (e.g.,
*.example.com) with GitHub Pages! A wildcard DNS record will allow anyone to host a GitHub Pages site at one of your subdomains.
For a list of supported custom domains, see "About supported custom domains."
GitHub Pages sites using custom domains that are correctly configured with
A DNS records can be accessed over HTTPS. For more information, see "Securing your GitHub Pages site with HTTPS."
It can take up to an hour for your GitHub Pages site to become available over HTTPS after you add and correctly configure your custom domain. After updating existing DNS settings, you may need to remove and re-add your custom domain to your GitHub account to trigger the process of enabling HTTPS. For more information, see "Using a custom domain with GitHub Pages."
If you've chosen to use Certification Authority Authorization (CAA) records, at least one CAA record must exist with the value
letsencrypt.org for your GitHub Pages site to be accessible over HTTPS. For more information, see "Certificate Authority Authorization (CAA)" in the Let's Encrypt documentation.
Custom domains configured with
If you configured your custom domain using an
A record, your
A record must point to one of the following IP addresses for HTTPS to work:
After updating any
A record IP addresses, you must remove and re-add your custom domain to the repository you’re using to publish your Pages site to trigger the process of enabling HTTPS. For more information, see "Configuring
A records with your DNS provider" in "Setting up an apex domain."
URL formatting error on Linux
Warning: If the URL for your GitHub Pages site contains a username or organization name that begins or ends in a dash, or contains consecutive dashes, then people browsing with Linux will receive a server error when they visit the site. To fix this, change your GitHub username to remove non-alphanumeric characters. For instructions on how to do this, see "Changing your GitHub username."