GitHub Pages 404: check the URL, publishing folder, and index file

A GitHub Pages 404 means the requested page was not found. It does not automatically mean you need a different host or a custom domain.

Start with the URL GitHub actually published, then check the folder and file behind it. This guide is for an existing Pages site, especially a small plain-HTML project. You need access to its repository—the place where its files and changes are stored.

First, open the deployed address

Open your repository on GitHub, select Settings, then Pages under Code and automation. If Settings is hidden, look in the repository’s tab overflow menu. Read the published address there and use Visit site if it is available.

A project repository named recipe-notes usually has an address shaped like:

https://YOUR_USERNAME.github.io/recipe-notes/

Do not omit /recipe-notes/. A user or organization site hosted from a repository named YOUR_USERNAME.github.io instead lives at the host’s root. A configured custom domain can produce a different address; use the actual Pages address rather than assuming either pattern.

If several unrelated GitHub Pages sites fail at the same time, check GitHub Status before changing your files.

Confirm which files Pages publishes

In Settings → Pages → Build and deployment, read the Source. Keep the current deployment method while diagnosing it.

If the source is Deploy from a branch, note both the branch and folder. The branch contains a version of your files; the folder selects which part becomes the site. Open the Code tab, switch to that exact branch, and inspect the selected folder.

• If the folder is /(root), index.html must be at the top of that branch.
• If the folder is /docs, the file must be docs/index.html on that branch.

An index.html in another branch or an extra website subfolder does not satisfy that setting.

If the source is GitHub Actions, the workflow builds and uploads a deployable set of files, called an artifact. The artifact’s top level needs the site’s entry file. Finding index.html somewhere in the repository does not prove it was included in that artifact. Inspect the existing workflow’s output/upload path; do not switch to branch publishing just to bypass a failing build.

Check the entry file and the missing page

For a plain HTML site, the entry filename must be exactly index.html. Index.html, index.HTML, and index.html.txt are different names. Open the file on GitHub and check that it contains your intended HTML.

Suppose your selected publishing folder contains:

index.html
about.html
images/

The home page is at /recipe-notes/, and the about page is at /recipe-notes/about.html. A link to /about.html asks for a file at the host’s root, outside this project. From the project’s home page, href="about.html" stays within its directory.

For a plain HTML file already on the selected branch, you can make a small correction in the browser:

1. In Code, select the publishing branch and open the affected file.
2. Choose the pencil Edit this file control; if hidden, check the file’s menu. Correct the filename in the filename field or the link in the text editor. Preserve the rest of the file.
3. Choose Commit changes, describe the correction, and commit to that publishing branch if you are allowed to. If branch protection requires a pull request, follow that repository’s review process instead; the deployment cannot include the correction until it reaches the publishing branch.
4. Return to Code and confirm the correct filename and contents on that branch.

If index.html belongs in the selected /docs folder, its repository path must be docs/index.html. Correct the file location through your normal repository workflow, preserving relative asset paths, rather than creating a second empty index to hide the problem.

If a local case-only rename is not reflected on GitHub, rename through a temporary distinct filename locally and commit the final correct name. Check the repository view again; your computer may treat letter case differently from the published site.

For a generated site, use the framework’s output files and base-path settings rather than moving source files at random. This plain-HTML example does not diagnose every framework’s routing system.

Wait for the corrected deployment

After saving and committing the correction to the source branch, open Actions. Inspect the newest Pages build/deployment run for that change, not an older successful run.

If it fails, open the failed job and its first relevant error. A failed new build can leave an earlier site live; refreshing the browser will not deploy the missing file. Fix that reported problem before testing the page again.

Once the deployment succeeds, open the exact address in a new tab:

1. Check the home page.
2. Open the formerly missing page directly.
3. Follow the site’s link to that page and confirm it reaches the same URL.

GitHub says publication can take up to ten minutes after a push. Wait for the deployment and that publication window before making another unrelated change. If the file exists in the correct output and the problem persists, use GitHub’s 404 checklist and check for an incident.

Keep DNS out of a file-path repair

If the home page loads on your custom domain but /about.html does not, start with the missing file or route. Changing DNS cannot create it.

A failure only on a custom domain needs a separate domain/Pages-setting check. Preserve working records and compare the actual configuration with GitHub’s official instructions. Do not remove a working custom domain or rewrite unrelated email records while fixing a page.

The repair is complete when the deployed home page and affected link both work—not merely when a repository contains an HTML file. If images still fail while the page loads, treat that as an asset-path problem rather than repeating the whole deployment setup.

Sources and useful links

• GitHub’s Pages 404 checklist — entry-file placement, capitalization, and domain checks.
• Configure a Pages publishing source — branch/folder publishing versus Actions.
• About GitHub Pages — site types and generated addresses.
• Create a Pages site — next step if this repository has never been published.