{"meta":{"title":"Troubleshooting 404 errors for GitHub Pages sites","intro":"This guide will help you troubleshoot common reasons you may be seeing a 404 error.","product":"GitHub Pages","breadcrumbs":[{"href":"/en/pages","title":"GitHub Pages"},{"href":"/en/pages/getting-started-with-github-pages","title":"Get started"},{"href":"/en/pages/getting-started-with-github-pages/troubleshooting-404-errors-for-github-pages-sites","title":"Troubleshoot 404 errors"}],"documentType":"article"},"body":"# Troubleshooting 404 errors for GitHub Pages sites\n\nThis guide will help you troubleshoot common reasons you may be seeing a 404 error.\n\n## Troubleshooting 404 errors\n\nIn this guide you'll find common reasons you may be seeing a 404 error while building your GitHub Pages site.\n\n* [GitHub's Status page](#githubs-status-page)\n* [DNS setup](#dns-setup)\n* [Browser cache](#browser-cache)\n* [`index.html` file](#indexhtml-file)\n* [Directory contents](#directory-contents)\n* [Custom domain](#custom-domain)\n* [Repository](#repository)\n\n### GitHub's Status page\n\nIf you see a 404 error while building a GitHub Pages site, first check GitHub's [Status page](https://githubstatus.com) for any active incidents.\n\n### DNS setup\n\nMake sure GitHub's DNS records are set up correctly with your DNS provider. For more information, see [Managing a custom domain for your GitHub Pages site](/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site).\n\n### Browser cache\n\nIf your GitHub Pages site is private and you see a 404 error, you may need to clear your browser's cache. For more information on clearing your cache, see your browser's documentation.\n\n### `index.html` file\n\nGitHub Pages will look for an `index.html` file as the entry file for your site.\n\n* Make sure you have an `index.html` file in the repository for your site on GitHub. For more information, see [Creating a GitHub Pages site](/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site).\n\n* The entry file must be at the top level of your chosen publishing source. For example, if your publishing source is the `/docs` directory on the `main` branch, your entry file must be located in the `/docs` directory on a branch called `main`.\n\n  If your publishing source is a branch and directory, the entry file must be at the top level of the source directory on the source branch. For example, if your publishing source is the `/docs` directory on the `main` branch, your entry file must be located in the `/docs` directory on a branch called `main`.\n\n  If your publishing source is a GitHub Actions workflow, the artifact that you deploy must include the entry file at the top level of the artifact. Instead of adding the entry file to your repository, you may choose to have your GitHub Actions workflow generate your entry file when the workflow runs.\n\n* The name of the `index.html` file is case sensitive. For example, `Index.html` will not work.\n\n* The name of the file should be `index.html`, not `index.HTML` or any other variation.\n\n### Directory contents\n\nCheck that your directory contents are in the root directory.\n\n### Custom domain\n\nIf you're using a custom domain, make sure it's set up correctly. For more information, see [About custom domains and GitHub Pages](/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages).\n\n* The `CNAME` record should always point to `<USER>.github.io` or `<ORGANIZATION>.github.io`, excluding the repository name. For more information about how to create the correct record, see your DNS provider's documentation.\n* If you are able to access your landing page, but encounter broken links throughout, it is likely because you either didn't have a custom domain name before or are reverting back from having a custom domain name. In such cases, changing the routing path does not initiate a rebuild of the page. The recommended solution is to ensure that your site rebuilds automatically when adding or removing a custom domain name. This may involve configuring a commit author and modifying the custom domain name settings.\n\n### Repository\n\nCheck whether your repository meets the following requirements.\n\n* The branch you are using to publish your site must be the `main` or default branch.\n* The repository must have a commit pushed to it by someone with admin permissions for the repository, such as the repository owner.\n* Switching the repository's visibility from public to private or vice versa will change the URL of your GitHub Pages site, which will result in broken links until the site is rebuilt.\n* If you are using a private repository for the GitHub Pages site, please check if your GitHub Pro, GitHub Team, or GitHub Enterprise Cloud subscription is still active. If you renew the plan, the GitHub Pages site will be automatically re-deployed. Otherwise, you can change your repository's visibility to public to continue using GitHub Pages for free.\n\nIf you are still receiving a 404 error, start a [GitHub Community discussion](https://github.com/orgs/community/discussions/categories/pages) in the Pages category."}