The 404 That Took Twenty Minutes to Fix

The 404 That Took Twenty Minutes to Fix

There is a particular kind of confidence that appears when a website works perfectly on your own computer.

You've refreshed it several times. The CSS is behaving. The buttons work. The images are where you left them. You've even made a final change to something completely unnecessary because apparently once a website works, the natural human response is to touch it again.

Then you publish it.

404.

During our July 2026 bootcamp, one of our students discovered this wonderful part of web development for the first time.

We had reached the stage of the programme where students were publishing their projects with GitHub Pages. This was a big moment because until then, their websites had lived on their laptops. They could open them with Live Server and show the person sitting beside them, but now we were putting them on the internet.

For the students, that distinction mattered enormously. A project feels different when it has a URL.

We pushed the student's project to GitHub, enabled GitHub Pages and waited for the deployment. Everything looked normal. GitHub gave us the link, we opened it and were greeted by a 404 page.

Fine. These things happen.

We checked the deployment again.

We refreshed.

Still 404, although I appreciate our optimism in believing the third refresh might cause GitHub to reconsider.

Then the investigation began.

Perhaps GitHub Pages hadn't finished deploying. Perhaps the repository settings were wrong. Perhaps we'd selected the wrong branch. Perhaps something strange had happened during the push. We checked the settings, looked through the repository and opened the site again.

At this point, the student's website was still working beautifully with Live Server, which made the whole thing more annoying. There it was on the laptop, happily proving that the website existed while the internet insisted it had never heard of it.

This is usually the point where beginners start believing they've broken something enormous.

They haven't.

One of the most useful things you can teach someone who is learning to code is that a dramatic-looking error can have an embarrassingly small cause. Computers don't assign importance to mistakes the way humans do. One tiny character can stop an entire program, and one file sitting in the wrong place can make a perfectly good website appear to have vanished.

After about twenty minutes of checking everything we thought could be wrong, we finally noticed it.

index.html was in the wrong folder.

That was it.

The homepage existed. The code was fine. GitHub was fine. The internet had not developed a personal disagreement with a child in Bonaberi.

Our index.html file was simply one level too deep.

The project looked something like this:

student-project/ website/ index.html style.css script.js

But GitHub Pages was publishing from the root of the repository. It was looking for the site's entry point there, while our homepage was sitting comfortably inside another folder waiting to be discovered.

We moved the files to the correct place, committed the change and pushed again.

Then we waited.

There is no suspense quite like watching someone repeatedly refresh a URL after fixing a bug. Everyone suddenly becomes extremely invested in the spinning browser icon.

This time, the website appeared.

The reaction was much bigger than the fix deserved, which is exactly how debugging works. Twenty minutes of confusion can make a correctly loaded homepage feel like you've personally repaired the internet.

The student was delighted. I was delighted. GitHub Pages presumably felt nothing.

But that little 404 taught something important.

When you're learning web development, it is tempting to think that becoming "good at coding" means reaching a point where things stop going wrong. Experienced developers know that this is absolutely not what happens. Things continue going wrong. You simply become less frightened when they do.

You learn to investigate.

If the website works locally but not online, what changed between those two environments? Is the deployment complete? Is the correct branch being published? Are your paths correct? Is the file GitHub expects actually where GitHub expects to find it?

Debugging becomes less like randomly changing things until the computer becomes happy and more like eliminating suspects from a very boring crime scene.

That is why we don't rush to fix every problem for our students.

It would have taken an instructor a few seconds to look through the repository, spot the nested folder and move index.html. The website would have been online faster, and we could have congratulated ourselves on running an efficient class.

The student would also have learned almost nothing.

Twenty minutes feels like a long time when you're eleven or fifteen and staring at a 404 page. But those twenty minutes teach you to look at file structures. They teach you that something working locally doesn't guarantee it will work after deployment. Most importantly, they teach you that an error message is not the computer announcing that you are bad at programming.

It's information.

Sometimes very unhelpful-looking information, admittedly, but information nonetheless.

If GitHub Pages is showing you a 404

If you've found this article because your own GitHub Pages website is currently displaying a 404, there is a decent chance you are having exactly the kind of afternoon we had.

Start by opening your GitHub repository and looking for index.html.

If you're publishing your site from the root of your main branch, a simple project will usually look something like this:

your-project/ index.html style.css script.js

If instead you see:

your-project/ some-other-folder/ index.html

check your GitHub Pages publishing configuration. GitHub needs to publish from the location containing the site you're trying to serve.

If the file structure looks correct, go to Settings, then Pages, and check that GitHub Pages is publishing from the branch and folder you intended. Give the deployment a little time to finish before deciding everything is broken. Also check the Actions tab if the deployment failed, because GitHub may already be telling you what went wrong.

And please resist the ancient debugging technique of refreshing the page seventeen times.

We tested it.

The eighteenth refresh doesn't fix it either.

Why we let students struggle

It can be uncomfortable to watch a beginner struggle with something when you already know the answer. Teaching creates a constant temptation to reach over, take the keyboard and make the problem disappear.

But the disappearing problem isn't always the goal.

At Giiyo Tech, we want students to experience the full process of building something. That includes the lovely moment when the page looks exactly how they imagined it, but it also includes the moment when absolutely nothing works and they have no idea why.

The second moment may actually be more valuable.

A student who has never encountered a bug can believe programming is about knowing the correct thing to type. A student who has spent twenty minutes hunting down a misplaced index.html begins to understand what programming actually feels like.

You build something.

Something breaks.

You investigate.

Eventually, you find the ridiculously small thing responsible.

Then you fix it and carry on.

By the end of our July bootcamp, every student had published a project online. Those live websites were something we were enormously proud of, but hidden behind every neat public URL were moments exactly like this one. Broken links, misplaced files and code that worked yesterday before somebody "improved" it.

Visitors will never see most of those mistakes.

The students will remember them.

And somewhere in Douala, there is now at least one young developer who will probably check where index.html is sitting before blaming GitHub.

Twenty minutes well spent.