Last updated: May 9, 2026 · Verified against current GitHub Actions deployment flow
You push changes to your GitHub repository and navigate to your github.io URL — only to be greeted by a 404 page, a blank white screen, or content that hasn't updated since your last push. Maybe your custom domain suddenly shows "This site can't be reached", or your GitHub Actions workflow shows red and you have no idea why the build failed. GitHub Pages is deceptively simple to set up but has several specific failure points that aren't obvious from the interface.
The good news is that nearly every GitHub Pages problem falls into one of seven categories, and most are fixable in under five minutes once you know where to look. This guide walks through each scenario in the most likely order you'll encounter them.
404 error on your github.io URL → Pages is likely not enabled or the source branch is wrong. Start with Fix 1.
Custom domain shows "not found" or "can't be reached" → DNS misconfiguration or missing CNAME file. See Fix 3 and Fix 4.
Site loads but shows old content after a push → Deployment may be stuck or failed. Check Fix 2 and try Fix 7.
HTTPS shows a certificate warning → Certificate not yet provisioned after custom domain setup. Wait up to 24 hours.
GitHub Actions shows a red X on deployment → Jekyll build error or configuration issue. See Fix 2 and Fix 5.
Site works for you but not for others → DNS propagation still in progress — normal within 48 hours of domain changes.
Why this matters: GitHub Pages is not automatically enabled on new repositories. You must explicitly turn it on and configure which branch to deploy from. If you haven't done this, or if the settings got reset, your site simply won't exist at the github.io URL.
main or gh-pages) and folder (usually / (root) or /docs).index.html at the exact path you selected.A very common mistake is deploying from the main branch root but having your HTML files inside a subdirectory. GitHub Pages serves exactly what is in the selected folder — your index.html must be directly there, not nested deeper inside another folder.
Why this matters: Modern GitHub Pages deployments use GitHub Actions workflows. When a build fails, your old site stays visible (or nothing shows at all for new repos), giving you no obvious indication something went wrong. The failure details are in the Actions tab.
_config.yml, a Liquid template error in an HTML file, or a missing file referenced in the config.If you see no workflow runs at all, your repository may be using the older "Deploy from a branch" method rather than Actions. In that case, look for a build status indicator on the Settings › Pages screen itself.
Why this matters: DNS records do not update instantly across the internet. When you change or add a custom domain, the old DNS records remain cached at ISPs and resolvers worldwide. Full propagation can take anywhere from a few minutes to 48 hours depending on the previous TTL (time-to-live) of your records.
To check propagation status, visit whatsmydns.net and enter your domain. It shows which DNS servers around the world have picked up the new records. For a GitHub Pages custom domain, your DNS records should point as follows:
185.199.108.153, 185.199.109.153, 185.199.110.153, and 185.199.111.153.yourusername.github.io.If whatsmydns shows your records are globally updated but the site still fails to load, the problem is configuration rather than timing — move on to Fix 4.
Why this matters: When you configure a custom domain in GitHub Pages settings, GitHub automatically creates a file called CNAME in your repository root. This file must exist and contain exactly your custom domain. If it gets deleted — for example by a git push that overwrites it — your custom domain stops working immediately.
CNAME (no extension, all caps) at the root level.www.yourdomain.com./dist folder), configure your build to copy the CNAME file as a build artifact before deployment.Why this matters: If your GitHub Pages site uses Jekyll (which it does by default unless you include a .nojekyll file), the _config.yml file is parsed on every deployment. A single YAML syntax error — a misplaced colon, inconsistent indentation, or an unclosed quote — causes the entire build to fail.
_config.yml in your repository.key: value not key:value), special characters in strings that need quoting, and an incorrect baseurl setting.yourusername.github.io/repo-name, your baseurl must be /repo-name. If it is at yourusername.github.io (user or org site), baseurl should be empty..nojekyll to your repo root to skip the Jekyll build entirely and serve your files directly.Why this matters: GitHub Pages for free accounts only works with public repositories. If your repository is private and you are on a free GitHub plan, Pages will not be available — the option will be grayed out in settings or the site will not load for visitors.
Why this matters: Sometimes GitHub Pages gets stuck and has not run a fresh build despite your pushes completing successfully. This can happen after GitHub infrastructure issues or when the last deployment partially completed. Pushing any commit — even an empty one with no file changes — triggers a fresh build cycle.
git commit --allow-empty -m "Force redeploy"git push origin main (replace main with your branch name if different).If you are not using git locally, you can trigger the same effect by making any trivial edit to a file directly on GitHub.com through the web interface and committing it there.
If you're seeing one of GitHub's specific error strings rather than a generic failure, the wording maps directly to the cause. Here's what each one actually means.
You typed your username.github.io URL and got a 404 page with this exact heading. It means GitHub itself is responding (so DNS is fine), but the repository it expected to serve doesn't have Pages enabled or doesn't exist with that exact name.
For a user site, the repo must be named username.github.io precisely. Capitals matter on the URL but the repo name itself must be lowercase. For a project site, you accessed username.github.io/repo but that repo doesn't have Pages turned on. Open the repo's Settings › Pages and pick a source branch.
You enabled Pages, picked a branch, but the green confirmation banner with your URL never shows up. This is almost always a build failure that GitHub doesn't surface clearly on the Pages settings page itself. Open the Actions tab and look for a red workflow run from the last few minutes. The actual error is in the build logs, not on the Pages screen.
The other reason: you picked a branch that doesn't actually contain an index.html at the source path you selected. GitHub will accept the configuration but won't show a live URL until there's something to serve.
You added a custom domain in Pages settings and got one of these red warnings. GitHub is doing a live DNS lookup against your domain and not seeing the records it expects. Three things can be wrong:
185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153. For a www subdomain, one CNAME pointing to username.github.io.dig yourdomain.com in a terminal or check whatsmydns.net. If your local resolver shows the right IPs but other regions don't, give it 1-24 hours.Click the "Check again" button on the Pages settings after each DNS change rather than waiting for GitHub to retry on its own schedule.
This appears in your GitHub Actions deployment logs when the build succeeded but GitHub couldn't actually publish the artifact to its Pages CDN. It usually means your repository is private but you're on a free plan, or your workflow is using actions/deploy-pages without the right permissions block.
Open your workflow YAML and confirm it has:
permissions: block at the top with pages: write and id-token: writeenvironment: block on the deploy job pointing to github-pagesIf you copied your workflow from an older example, the deploy step changed in late 2022 to require these. Older Action workflows that pushed directly to a gh-pages branch still work, but the official deploy-pages path needs the explicit permissions.
GitHub emails the repo owner when a Jekyll build fails. The email subject is usually "Page build failure" and the body lists the offending file and line. Most common causes I've actually seen:
:, #, @ at the start of a value).{{ page.foo }} if foo doesn't exist.If you don't actually use Jekyll and just want plain HTML served, drop a zero-byte file named .nojekyll at the root of your branch. GitHub skips Jekyll entirely and serves your files raw. This eliminates an entire category of build failures.
Your site loads but clicking an internal link takes you to GitHub's 404 page. Two common causes:
About.html but your file is about.html. GitHub Pages serves from a case-sensitive Linux filesystem, so this fails even though it works on Windows or macOS local previews. Always use lowercase filenames and lowercase links./blog/ needs an index.html inside that folder. A link to /blog without the slash needs a blog.html file at the parent level. Pick one convention and stick to it.You can ship a custom 404.html file at the root to replace GitHub's default 404 page with something on-brand.
The page returns 200 OK but renders empty. Open your browser's DevTools console (F12) and check for JavaScript or asset 404s. The usual suspects:
/style.css on a project site at username.github.io/repo. The browser resolves these to username.github.io/style.css, which doesn't exist. Use relative paths (./style.css) or the baseurl setting.<script> tag that throws and halts page rendering before any visible content paints.display: none on the body or main container, often from an unfinished theme.Your site loads on HTTP but you get a certificate warning on HTTPS, or the "Enforce HTTPS" checkbox stays disabled in Pages settings. GitHub uses Let's Encrypt and provisions the cert only after DNS fully resolves. Common gotcha: a Cloudflare proxy in front of your domain blocks the validation. If you use Cloudflare, set the DNS record to "DNS only" (gray cloud, not orange) until the cert issues, then you can re-enable proxying with Cloudflare's own SSL.
Provisioning takes anywhere from a few minutes to 24 hours. If "Enforce HTTPS" is still grayed out after 48 hours, remove the custom domain from Pages settings, save, then re-add it. This forces GitHub to retry the certificate request.
Q: How long does GitHub Pages take to deploy?
A: GitHub Pages typically deploys within 1 to 3 minutes for simple static sites. Jekyll builds and custom Actions workflows can take up to 10 minutes. If your deployment has not completed after 20 minutes, check the Actions tab for a failed workflow run. First-time HTTPS certificates for custom domains can take up to 24 hours to issue after DNS propagation completes.
Q: Can I use a custom domain with GitHub Pages for free?
A: Yes. Custom domains are fully supported on free GitHub accounts as long as the repository is public. You need to own the domain, configure DNS records pointing to GitHub's servers, and add a CNAME file to your repository root. GitHub handles HTTPS certificate provisioning automatically at no cost through Let's Encrypt.
Q: Why is my GitHub Pages site showing old content?
A: Old content after a push almost always means your browser has cached the previous version. Try a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) or open the site in an incognito window. If content is genuinely stale after that, check the Actions tab to confirm the latest deployment completed successfully — a failed build leaves the old site in place.
Q: Does GitHub Pages support HTTPS automatically?
A: Yes. GitHub Pages provides automatic HTTPS for both github.io subdomains and custom domains. For github.io URLs it is active immediately with no configuration needed. For custom domains, GitHub provisions a free Let's Encrypt certificate automatically once your DNS records have correctly propagated — this can take up to 24 hours after initial custom domain setup.
Q: Can GitHub Pages run server-side code?
A: No. GitHub Pages is a static file hosting service only — it serves HTML, CSS, JavaScript, and static assets. There is no support for PHP, Python, Node.js, databases, or any server-side execution. If your project needs a backend, you must host it separately on a service like Render, Railway, or a VPS, and call it from your GitHub Pages frontend using JavaScript API requests.
If you have worked through all seven fixes and your GitHub Pages site still will not load, the official GitHub Pages documentation has detailed troubleshooting for advanced scenarios: docs.github.com/en/pages. The GitHub Community forums are also a good resource for repository-specific build failures.