Not found errors

GitHub Pages shows a 404 instead of your site

Your github.io address shows GitHub's own 404 page instead of your site.

Checked 16 October 2026

The short answer

Usually Pages isn't publishing yet, or what it publishes has no index.html at the top. Check that Settings → Pages shows your site as live, and that index.html sits at the root of the published folder.

Find your cause

6 causes, most likely first

  1. 1

    Pages isn't switched on, or the source is wrong

    How to tell: The Pages settings don't show a live address for your site.

    Fix

    Under Build and deployment, choose GitHub Actions if the site needs a build, or Deploy from a branch and pick the branch and folder that hold your files.

    Settings→Pages→Build and deployment

  2. 2

    The workflow didn't run, or failed

    How to tell: The Actions tab shows a red cross, or no run at all.

    Fix

    Open the failed run and read the first error: most often a missing lockfile, a Node.js version or a build error. Fix it and push again, or start it by hand with Run workflow.

  3. 3

    index.html isn't at the top of what's published

    How to tell: index.html sits in a subfolder (dist/, site/), or it's called Index.html.

    Fix

    The entry file has to be at the top level of what's published, named index.html in lowercase. Point the workflow's upload path at your build folder, or the branch setting at the folder with index.html in it.

  4. 4

    You're opening the wrong address

    How to tell: The repository isn't named USERNAME.github.io, and you're opening USERNAME.github.io without /REPO/ after it.

    Fix

    Project sites live at USERNAME.github.io/REPO/. Only a repository named USERNAME.github.io is served at the root.

  5. 5

    A private repository without a paid plan

    How to tell: The repository is private and the account is on GitHub Free, or a paid plan has lapsed.

    Fix

    Publishing from a private repository needs a paid plan. Make the repository public, or renew the plan; the site comes back by itself.

  6. 6

    It's just been published

    How to tell: You switched Pages on or pushed moments ago.

    Fix

    A first publish can take a few minutes. Check the deployment in the Actions tab, then reload. If everything looks right, check githubstatus.com for an incident.

Questions

Also asked

My README shows instead of my site. Why?

With Deploy from a branch and no index.html, GitHub Pages builds the README into a page. Add an index.html at the top of the published folder, or publish your build folder with a workflow.

The site worked and now it's a 404. What changed?

Look for a failed run in the Actions tab, a change of visibility (which changes the address), or a custom domain that was removed.

Rather skip build settings altogether?

Build on your computer, where it already works, and drop the folder on 99helpers. The site gets its own address, so there's no base path, workflow or build log to get wrong, and it's online in seconds.

Drop your folderHow, for your framework

Or skip the setup

Drop it in. It's online in seconds.

A file, a folder or a whole site: 99helpers puts it online at its own address, with no git, no build settings and no DNS to start with. Add your own domain whenever you're ready.

Put it online freeWhere should I host it?