Guide: Troubleshooting 404 errors for GitHub Pages sites #61073
Replies: 14 comments 17 replies
-
Thank you |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
Please add another reason is that your folders may start with Credit to mpetrovich/stylemark#65. |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
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 :/ |
Beta Was this translation helpful? Give feedback.
-
github.com/user |
Beta Was this translation helpful? Give feedback.
-
Hello everyone My repository is there: Could you help me please? |
Beta Was this translation helpful? Give feedback.
-
It's not working! It's driving me crazy! *Simple workflow for deploying static content to GitHub Pages on:
jobs:
I don't know, but it says I don't have the rights to change some things... Error: .github#L1 IM THE ... OWNER!!! What's happen? 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! name: Deploy to GitHub Pages on: jobs:
Please fix this fast! it's the worst for newbies :( |
Beta Was this translation helpful? Give feedback.
-
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? |
Beta Was this translation helpful? Give feedback.
-
Hi, can you add a guide about |
Beta Was this translation helpful? Give feedback.
-
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? |
Beta Was this translation helpful? Give feedback.
-
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. 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 |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
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
fileGitHub 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 themain
branch, your entry file must be located in the/docs
directory on a branch calledmain
.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 themain
branch, your entry file must be located in the/docs
directory on a branch calledmain
.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
, notindex.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.
CNAME
record should always point to<USER>.github.io
or<ORGANIZATION>.github.io
, excluding the repository name.Repository
Check whether your repository meets the following requirements.
main
or default branch.Pages Deployment Update
TL;DR: try adding a
.nojekyll
file to the root of your repoSpecial thanks to:
_
issuesGitHub 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 yourmain
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.
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!
Beta Was this translation helpful? Give feedback.
All reactions