Skip to main content

This version of GitHub Enterprise Server was discontinued on 2024-07-09. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

Troubleshooting 404 errors for GitHub Pages sites

This guide will help you troubleshoot common reasons you may be seeing a 404 error.

Who can use this feature?

GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.

Troubleshooting 404 errors

In this guide you'll find common reasons you may be seeing a 404 error while building your GitHub Pages site.

GitHub's Status page

If you see a 404 error while building a GitHub Pages site, first check GitHub's Status page for any active incidents.

Browser cache

If 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.

index.html file

GitHub Pages will look for an index.html file as the entry file for your site.

  • Make sure you have an index.html file in the repository for your site on GitHub Enterprise Server. For more information, see "Creating a GitHub Pages site."

  • 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.

    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.

    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.

  • The name of the index.html file is case sensitive. For example, Index.html will not work.

  • The name of the file should be index.html, not index.HTML or any other variation.

Directory contents

Check that your directory contents are in the root directory.

Repository

Check whether your repository meets the following requirements.

  • The branch you are using to publish your site must be the main or default branch.
  • The repository must have a commit pushed to it by someone with admin permissions for the repository, such as the repository owner.
  • 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.

If you are still receiving a 404 error, start a GitHub Community discussion in the Pages category.