FixThatApp
🔍

GitHub Pages Not Loading: 7 Fixes for Deployment Issues

Last updated: April 3, 2026

By Sufyan Khan — Founder, FixThatApp  |  Editorial standards

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.

Quick Diagnosis: What Symptom Do You Have?

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.

7 Fixes for GitHub Pages Not Loading

Fix 1: Check Repository Settings — Is Pages Actually Enabled?

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.

  1. Navigate to your repository on GitHub.com.
  2. Click the Settings tab at the top of the repository.
  3. In the left sidebar, click Pages under the "Code and automation" section.
  4. Under "Build and deployment", confirm the Source is set to your correct branch (usually main or gh-pages) and folder (usually / (root) or /docs).
  5. If Pages was not enabled, set it up now. GitHub will begin building and display your URL when complete.
  6. If it says "Your site is live at..." but still shows 404, confirm the branch contains an 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.

Fix 2: Check GitHub Actions Deployment Logs for Build Errors

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.

  1. Go to your repository and click the Actions tab.
  2. Look at the most recent workflow run. A red circle means it failed; yellow means it is in progress; green means success.
  3. Click into the failed run and expand the build steps to read the error message.
  4. Common errors include: missing Jekyll dependency, YAML syntax error in _config.yml, a Liquid template error in an HTML file, or a missing file referenced in the config.
  5. Fix the underlying issue in your repository, push again, and watch the Actions tab for the new run.

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.

Fix 3: Wait for DNS Propagation After a Custom Domain Change

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:

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.

Fix 4: Verify the CNAME File Is in Your Repository Root

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.

  1. Browse your repository's file list on GitHub.com.
  2. Look for a file named CNAME (no extension, all caps) at the root level.
  3. Click it and confirm it contains your custom domain on a single line — for example: www.yourdomain.com.
  4. If the CNAME file is missing, go to Settings › Pages and re-enter your custom domain. GitHub will recreate the file automatically.
  5. If your build process deletes the CNAME file on each deploy (common with static site generators outputting to a /dist folder), configure your build to copy the CNAME file as a build artifact before deployment.

Fix 5: Check _config.yml for Syntax Errors

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.

  1. Open _config.yml in your repository.
  2. Check for: tabs instead of spaces for indentation, missing space after a colon (write key: value not key:value), special characters in strings that need quoting, and an incorrect baseurl setting.
  3. If your site is at 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.
  4. Validate your YAML at yamllint.com before pushing.
  5. If you do not need Jekyll processing at all, add an empty file called .nojekyll to your repo root to skip the Jekyll build entirely and serve your files directly.

Fix 6: Make the Repository Public or Check Your GitHub Plan

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.

  1. Go to your repository Settings › General and scroll to the "Danger Zone" at the bottom.
  2. Check whether the repository is set to Private.
  3. If you need to keep it private, you will need GitHub Pro, GitHub Team, or GitHub Enterprise to use Pages with private repositories.
  4. If making the repo public is acceptable, click "Change visibility" and set it to Public.
  5. After changing to public, re-enable Pages in Settings › Pages if it had been previously unavailable.

Fix 7: Force a Redeploy by Pushing an Empty Commit

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.

  1. Open your terminal and navigate to your local repository folder.
  2. Run: git commit --allow-empty -m "Force redeploy"
  3. Then run: git push origin main (replace main with your branch name if different).
  4. Go to the Actions tab on GitHub and watch the deployment progress in real time.
  5. Once the workflow shows a green checkmark, wait 1 to 2 minutes and visit your site URL with a hard refresh (Ctrl+Shift+R on Windows, Cmd+Shift+R on Mac).

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.

What NOT to Do

Common mistakes that make this worse
  • Don't push fixes and check the live site within 30 seconds. GitHub Pages deployments take 1-5 minutes to build and propagate after a push. Checking immediately after a commit will almost always show the old version. Wait for the Actions workflow to show a green checkmark before concluding your change didn't work.
  • Don't assume a 404 error means your files are missing. The most common cause of a 404 on GitHub Pages is that the publishing source branch or folder is misconfigured in repository settings. Check Settings → Pages to confirm GitHub Pages is pointing at the correct branch (main or gh-pages) and the correct folder (root or /docs) before assuming you need to re-upload files.
  • Don't name your main HTML file anything other than index.html at the root. GitHub Pages serves index.html as the default document for a directory. If your main file is named home.html, landing.html, or anything else, visiting your site's root URL returns a 404 even when the file is correctly present in the repository. The file must be named index.html exactly.
  • Don't use absolute paths for internal links and assets in a project subdirectory site. If your GitHub Pages site is at username.github.io/reponame, absolute paths like /style.css will fail — they resolve to username.github.io/style.css instead of the correct subdirectory path. Use relative paths or the Jekyll baseurl setting to handle this correctly.

Frequently Asked Questions

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.

Still Stuck?

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.

Related Guides