Guide: Troubleshooting 404 errors for GitHub Pages sites

[queenofcorgis]

Getting the dreaded 404 error while building a GitHub Page is no fun 👎 and can often be confusing as you work to set up your site. We’ve compiled common reasons you may be seeing the 404 error while working with GitHub Pages. This guide will help you troubleshoot common reasons you may be seeing this 404 error and also lives in our docs!

Troubleshooting 404 errors

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.

DNS setup

Make sure GitHub's DNS records are set up correctly with your DNS provider. For more information, see Managing a custom domain for your Pages site or search in the community.

Browser cache

If your 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 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. For more information, see Creating a GitHub Pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-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.

Custom domain

If you're using a custom domain, make sure it's set up correctly. For more information, see About custom domains and GitHub Pages.

• The CNAME record should always point to <USER>.github.io or <ORGANIZATION>.github.io, excluding the repository name.
• 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.

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.

Pages Deployment Update

TL;DR: try adding a .nojekyll file to the root of your repo
Special thanks to:

• @nectariferous for some helpful Jekyll tips.
• @datvm For pointing out the Jekyll _ issues
• @Tryanks for requesting updated documentation

GitHub Pages now uses GitHub Actions to execute the Jekyll build. When using a branch as the source of your build, GitHub Actions must be enabled in your repository if you want to use the built-in Jekyll workflow. Alternatively, if GitHub Actions is unavailable or disabled, adding a .nojekyll file to the root of your source branch will bypass the Jekyll build process and deploy the content directly. For more information on enabling GitHub Actions, see "Managing GitHub Actions settings for a repository."

Translation: If you are using a front end framework other than Jekyll to create your site, and you are running into deployment errors, create a file named .nojekyll and put it in the root directory of your main branch; then run your build/deployment again.

Antora's documentation for deployment is excellent, and it can apply to other front end frameworks as well.

By default, GitHub Pages runs all files through another static site generator named Jekyll (even if your repository is not set up to use Jekyll). Since Antora already produces a ready-made site, there’s absolutely no need for this step. But it’s more than just the wasted effort.

Jekyll has the nasty side effect of removing all files that begin with an underscore (_). Why is this a problem? By default, Antora puts UI files in a folder named _. It also places images inside the folder named _images. When Jekyll comes through, it wipes out these folders. As a result, you get no UI and no images.

.nojekyll
Fortunately, there’s a way to disable this “feature” of GitHub Pages. The solution is to add a .nojekyll file to the root of the published site (i.e., the output directory configured in your playbook).

The presence of the .nojekyll file at the root of the gh-pages branch tells GitHub Pages not to run the published files through Jekyll. The result is that your Antora-made site will work as expected.

Now that you have this guide, feel free to use it to assist in solving other members’ posts in the GitHub Community and spread the knowledge wealth 🧠.

Still receiving a 404 error? Start a discussion and share as many details as you can.

Are we missing any common blockers or you want to see more guides like this? Let us know in the comments!

[devrose04]

Thank you

[ShinichiKikukawa]

thx

[RAVIBANKA27]

I am facing a problem only on uploading index.js file, it shows me 404 error for only index.js file in the inspect window

[RosmerySI]

Hi could you find a solution ?I am facing the same problem with js file and also css file

[Atul9569]

When you encounter a 404 error on your GitHub Pages site, it usually means that the server couldn't find the requested page. This can happen for a few reasons, but don't worry, we'll work through them step by step.

Here's a guide to help you troubleshoot those pesky 404 errors:

Check Your File Paths: The first thing to do is make sure your file paths are correct. Double-check that you've specified the right file names and folder locations in your URLs and links. Remember, GitHub Pages is case-sensitive, so "Page.html" and "page.html" are considered different files.

Branch and Directory Settings: If your site isn't showing up, make sure that the branch you're using for GitHub Pages is correct. Also, confirm that your site's main HTML file (like "index.html") is in the root directory of your repository.

Wait for Changes to Reflect: If you've recently made changes to your site, remember that it might take a little time for those changes to be visible due to caching. Give it a bit of time, or try clearing your browser cache.

GitHub Pages Build: Sometimes, a 404 error might be caused by a problem during the GitHub Pages build process. Make sure your repository has been successfully built. You can check the "Settings" tab in your repository for GitHub Pages build logs.

Link Errors: If you're linking to external resources like CSS, JavaScript, or images, ensure that the URLs are correct. An incorrect link could lead to a 404 error.

File Extensions: GitHub Pages often assumes that files like "Page.html" should be accessed as "page.html". Check if your file extensions and URLs are consistent.

Repository Permissions: Ensure that your repository is public if you intend for your GitHub Pages site to be accessible to everyone. Private repositories won't be visible to the public.

Custom Domain: If you're using a custom domain, make sure your DNS settings are properly configured. Incorrect settings could lead to 404 errors.

Typos in URLs: It's easy to overlook typos in URLs. Make sure there are no typos in your links and URLs that could be causing the issue.

GitHub Status: Occasionally, GitHub itself might experience issues that can result in temporary disruptions. You can check the GitHub Status page to see if there are any ongoing problems.

By following these steps, you should be able to narrow down the cause of the 404 error on your GitHub Pages site and get it back up and running smoothly.

[queenofcorgis]

While we encourage non-AI answers to questions in community, we also love experimenting and using new technologies. We ask if you do use ChatGPT or similar programs, please disclose what software and model version number you used to generate the response you used in your reply in order to promote transparency in the community.

ChatGPT answers in a tone that sounds like a tech support professional and while we support trying out this software, it is important to verify that they are solutions before posting otherwise it may mislead users into thinking that they are receiving official responses when they are not.

Per ChatGPT's website, the program does have limitations like:

• "May occasionally generate incorrect information"
• "May occasionally produce harmful instructions"
• "Limited knowledge of world and events after 2021"

[datvm]

Please add another reason is that your folders may start with _ (underscore), for example Blazor's _framework and _content. You have to add a .nojekyll file into your root directory.

Credit to mpetrovich/stylemark#65.

[queenofcorgis]

@datvm thank you for suggesting this addition! This is a new one I haven't heard of so if you start a folder with _ it must have a .nojekyll file in the root directory?

[datvm]

@queenofcorgis Yes. I am not sure why but apparently Github processes the pages through Jekyll which does not output folders that starts with _.

With that file in the root directory it doesn't get processed and just output all the files/folders I think. It was kinda a frustrated experiement because all my other files (like /css/app.css) work fine but all files in _framework folder results in 404.

UPDATE: yep it's confirmed from the blog post:

It is now possible to completely bypass Jekyll processing on GitHub Pages by creating a file named .nojekyll in the root of your pages repo and pushing it to GitHub. This should only be necessary if your site uses files or directories that start with underscores since Jekyll considers these to be special resources and does not copy them to the final site.

[AdrianoRean]

I would suggest to add that if you are using Jekyll, you must know that by default files and directories that start with "_" will be ignored.

[cpi28]

I'm trying to deploy a web page with react and vite, I've followed all the steps you mentioned before but I still have a 404 response :/

[queenofcorgis]

@cpi28 oh no sorry to hear you're still having trouble! I would suggest opening a new post in this category detailing what you're experiencing and what you've tried so others can assist 👍🏼

[joominho1234]

I

[blackholeapp]

github.com/user
I need different github.io page with different username

[anoma3]

Hello everyone
I hope my messge finds you well.
I am new in github. I have been trying to publish my assignment for a few hours now. The adress I want to visualise should be this one:
https://anoma3.github.io/module5-solution/index.html
It worked for my previous assignments, but this time I get a 404 error and I do not understand why.

My repository is there:
https://github.com/anoma3/module5-solution

Could you help me please?

[queenofcorgis]

@anoma3 thanks for posting in the community! I would suggest opening a new post in this category detailing what you're experiencing and what you've tried so others can assist 👍🏼 you're likely to get better visibility that way.

[Jamancode]

It's not working! It's driving me crazy!
Ur static page stuff is broken.
static.yml

*Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:

• Runs on pushes targeting the default branch
  push:
  branches: ["main"]

• Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

• Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
  permissions:
  contents: read
  pages: write
  id-token: write

• Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.

• However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
  concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:

• Single deploy job since we're just deploying
  deploy:
  environment:
  name: github-pages
  url: ${{ steps.deployment.outputs.page_url }}
  runs-on: ubuntu-latest
  steps:
  • name: Checkout
    uses: actions/checkout@v4
  • name: Setup Pages
    uses: actions/configure-pages@v4
  • name: Upload artifact
    uses: actions/upload-pages-artifact@v3
    with:
    • Upload entire repository
      path: '.'
  • name: Deploy to GitHub Pages
    id: deployment
    uses: actions/deploy-pages@v4

I don't know, but it says I don't have the rights to change some things...

Error: .github#L1
actions/checkout@v4, actions/configure-pages@v4, actions/upload-pages-artifact@v3, and actions/deploy-pages@v4 are not allowed to be used in gitmonkey/gitmoneky.github.io. Actions in this workflow must be: within a repository owned by gitmonkey.

IM THE ... OWNER!!! What's happen?
I've configured all the rights and options, it's on the main branch, and I've checked everything, but none of it seems to be working. It's really frustrating.

Now, I'm utilizing the old version I had stored. However, when attempting to operate with version v4, it feels like colliding my head against the hard wall of reality, as it simply doesn't function.

use this!
deploy.yml

name: Deploy to GitHub Pages

on:
push:
branches:
- master

jobs:
build:
runs-on: ubuntu-latest

steps:
  - uses: actions/checkout@v2
  - name: Install dependencies
    run: |
      npm install
  - name: Build and deploy
    run: |
      npm run build
      npx gh-pages -d build

Please fix this fast! it's the worst for newbies :(

[LiteBrite82]

Hi @Jamancode

I know this is a few months late, but I found an answer Actions in this workflow must be: within a repository owned by #26609.

TL;DR: You need to adjust your account Actions Permissions Managing GitHub Actions permissions for your repository

[ECGonzales]

I am getting a 404 error about my page not being found. It has been working for quite a while and I haven't made any updates to my page since 5 months ago and it all of a sudden stopped working. Has something change in the last few months with the structure?

[LiteBrite82]

Hi @ECGonzales

Sorry I missed your question.

Did you get any help with this yet? if not, can you please create a new discussion in the Pages category so its easier to track.

[Tryanks]

Hi, can you add a guide about .nojekyll to the 404 docs and add it with the first post of this discussion? I was trying to deploy my Avalonia WASM project and was held up for a long time until I saw the reply from @datvm which solved the issue. I had also gone through the docs before, but there were no relevant instructions in there :(
This entry would help people like me who are looking to deploy Avalonia/Blazor.

[LiteBrite82]

@Tryanks
Can Do!

[peddireddyShivareddy]

I am getting 404 error still everything is made correct, i have index.html and main branch as default still i am getting this error it is worked before. but it is not working now?

[LiteBrite82]

Hi @peddireddyShivareddy

Can you create a new discussion in `pages' for this issue and provide a link to the problem repo?

[nectariferous]

Thanks for putting together this awesome guide on tackling those pesky 404 errors. Mind if I chip in with a few more ideas? I've banged my head against this wall a few times, so here are some extra things to check that might save someone else a headache:

Jekyll being Jekyll: If you're using Jekyll (which a lot of us do), sometimes it throws a fit. Check your build logs for any drama, and make sure your Gemfile and _config.yml are playing nice.
File permission shenanigans: This one's a bit techy, but sometimes file permissions get wonky. Make sure your files are set to 644 and folders to 755. It's like making sure everyone has the right backstage pass to your site.
The sneaky .gitignore: Ever added something to your .gitignore and then wondered why it's not showing up? Yeah, been there. Maybe take a peek and make sure you haven't accidentally told Git to ignore something important.
Size matters: Did you know GitHub Pages has a size limit? 1GB for the whole repo and 100MB per file. If you're going big, you might need to trim things down a bit.
Case sensitivity chaos: This one's bitten me before. GitHub Pages is super picky about uppercase and lowercase. So index.html and Index.html are totally different things to it. Double-check all your file names and links!
The cache strikes back: Sometimes your browser is just showing you old stuff. Try hard refreshing (Ctrl+F5 usually does the trick) or open an incognito window to see if that fixes things.
Path problems: If you're working on a project page (like username.github.io/coolproject), make sure all your links include the project name. It's easy to forget and end up with broken links all over the place.

Hope these extra tips help someone out there avoid pulling their hair out over a 404! If anyone's still stuck after all this, don't be shy

[LiteBrite82]

@nectariferous

Thanks for the fantastic tips!!!

[ahumellihuk]

Thanks for the tip about size limit! I don't believe we even hit 1Gb in the gh-pages branch, but some of the subdirectories we pushed recently were returning 404 Not Found until I deleted some of the older stale ones we didn't need anymore. Hope this helps someone else!

[kasir-barati]

Hey @nectariferous,

Just wanna make sure I get it right, according to your comment I had to include the "project name" in my links. So now I have this GH Pages for my "react" repo: https://kasir-barati.github.io/react/

And I am getting 404 when I click on any link inside the index page. I am not sure what is wrong since I have also this GH Pages and it is working just fine: https://kasir-barati.github.io/the-pragmatic-programmer/

The only difference between them is that in my the-pragmatic-programmer repo I am not using .github/docs as you can see here: https://github.com/kasir-barati/the-pragmatic-programmer/blob/main/index.md?plain=1

But in my react repo I am: https://github.com/kasir-barati/react/blob/main/index.md?plain=1

So I am confused and is trying to figure it out what is different between these two? Is Jekyll making a fuss over using .github directory (I mean it starts with a dot so I guess it is hidden)? Or am I doing something else wrong?

Jesus, I just finished publishing a post on LinkedIn bragging about GH Pages 😂.

[kasir-barati]

@LiteBrite82 Any comment? Also please if possible add the fact that index.md works too as long as we have a _config.yml at the root of our repo. GH takes care of building it for you automatically to the first message as it might help some people.

This is of course my understanding and might not be the most accurate out there.

[kasir-barati]

It seems I was right about that: https://jekyllrb.com/docs/configuration/options/

Search for:

dotfiles are excluded by default.

[javy99]

This guide offers a solid breakdown of common causes behind the 404 error on GitHub Pages, from DNS setup to ensuring the proper placement of the index.html file. The recommendation to add a .nojekyll file is especially helpful for users not relying on Jekyll, as it prevents unwanted file deletions. It's a comprehensive resource for troubleshooting GitHub Pages, but if issues persist, starting a discussion with detailed info is a good next step.