Your GitHub portfolio shouldn’t be harder to set up than fixing a typo in your code. Most 404 errors or blank pages? Usually just a quick repo setting or a misnamed file. Here’s the troubleshooting path I walk developers through almost every week.
Quick Fix Summary
Make a repo called username.github.io (swap in your actual GitHub handle). Drop an index.html file in the root folder. Wait up to two minutes for the CDN to catch up. Your portfolio should appear at https://username.github.io.
What’s Going on Behind the Scenes
GitHub Pages serves your portfolio from a special repo—its name must match your username exactly, capital letters and all. The CDN caches the first request for up to two minutes, so a 404 right away is normal while the edge servers sync up. If you’re seeing anything other than a blank page or 404, the usual suspects are:
- A repo name that doesn’t match your handle exactly
- An
index.htmlfile missing from the root or named something else - GitHub Pages still set to “None” in the repo settings
- DNS caching on your computer or your ISP’s side
How to Fix It Step by Step
Double-check your repo name
- Spin up a new public repository named exactly
username.github.io(yes, uppercase letters matter). - Clone it:
git clone https://github.com/username/username.github.io
- Spin up a new public repository named exactly
Drop in a bare-bones index.html
- Inside the repo, create a file called
index.htmlwith one line:<h1>Hello World</h1> - Commit and push:
git add . && git commit -m "initial" && git push
- Inside the repo, create a file called
Turn on GitHub Pages
- Head to Settings → Pages.
- Under Source, pick Deploy from a branch.
- Choose branch: main (or master if you haven’t switched it).
- Folder: / (root).
- Hit Save.
Wait and reload
- Give it 60–120 seconds. Then hard-refresh your browser (Ctrl+F5 or Cmd+Shift+R).
- Visit https://username.github.io. You should see “Hello World”.
Still Not Working?
DNS or ISP caching
Try from another network or clear your DNS cache: Windows users run
ipconfig /flushdns; macOS users runsudo dscacheutil -flushcache; Linux users runsudo systemd-resolve --flush-caches.Wrong branch or folder
Revisit Settings → Pages. The branch must be main (or master), and the folder must be /. If you previously used docs, switch to /root.
CORS or ad-blocker issues
Turn off browser extensions temporarily. On a work network? Ask IT if outbound HTTPS on port 443 is blocked.
How to Keep This From Happening Again
| Action | Why It Matters |
|---|---|
| Always name the repo exactly username.github.io | GitHub Pages only auto-discovers the site when the repo name matches your username exactly. |
| Keep index.html in the root | Any subfolder forces a path like /repo-name/, which breaks the default expectation. |
| Use main as your default branch | Since late 2020, GitHub Pages defaults to main—older repos using master still work, but sticking with main cuts down on mistakes. |
| Enable HTTPS enforcement | In Settings → Pages → Enforce HTTPS (it’s on by default). HTTPS is required for most job-application forms these days. |
I once helped a friend whose portfolio stayed on 404 for hours because his ISP cached the old GitHub IP for a full day. Flushing DNS solved it in seconds. Good trick to remember.
Once that skeleton page loads, swap in your real portfolio files. Three things matter most: repo name, root file, and HTTPS. Nail those, and the CDN handles the rest.
