Skip to main content

Solved: GitHub Pages 404 "There isn't a GitHub Pages site here"

 You have pushed your code, verified your commits, and navigated to your GitHub Pages URL, only to be greeted by a 404 error stating "There isn't a GitHub Pages site here."

This is the most common hurdle for students and beginners deploying their first portfolio or project. It usually does not mean your code is broken. It means the mapping between GitHub’s routing service and your repository’s file structure is misaligned.

This guide provides the technical root cause analysis and the exact configuration steps required to resolve this error for HTML and Jekyll projects.

Root Cause Analysis: The "Source" Disconnect

To fix the problem, you must understand how GitHub Pages serves content. Unlike a dynamic server (like Node.js or PHP) that processes requests on the fly, GitHub Pages is a static file server. It looks for an entry point—specifically an index.html file—in a specific location.

The "There isn't a GitHub Pages site here" error occurs when the internal Nginx router at GitHub cannot determine which Branch or Folder serves as the production source.

The master vs. main Conflict

Historically, Git repositories initialized with a default branch named master. In 2020, GitHub shifted the default branch name to main for inclusivity.

However, many older GitHub Pages configuration defaults still look for master. If your repository uses main (which it likely does if created recently) and the Pages settings are looking for master, the deployment pipeline fails silently or returns a 404.

The Root vs. Docs Conflict

By default, GitHub Pages expects your index.html to be at the root (/) of your repository. If you have organized your project by placing your source code in a /src, /public, or /docs folder to keep things tidy, GitHub Pages looks at the root, finds nothing, and throws a 404.

Solution 1: Configure Build and Deployment Settings

This is the most direct fix for static HTML and standard Jekyll sites.

  1. Navigate to your repository on GitHub.
  2. Click the Settings tab (usually the rightmost tab in the top navigation bar).
  3. In the left sidebar, scroll down to the "Code and automation" section and click Pages.

Correcting the Branch

Under the Build and deployment section, verify the "Source" is set to Deploy from a branch.

Look at the Branch dropdown menu.

  • Current State: It may say "None" or be selected to a branch that does not exist.
  • The Fix: Select your primary working branch. This is usually main. Do not select gh-pages unless you are explicitly using a build tool that pushes compiled code to that specific branch.

Correcting the Folder

Immediately next to the branch dropdown is the folder dropdown.

  • Option A (/ root): Select this if your index.html file is visible immediately when you open your repository code.
  • Option B (/docs): Select this only if you have moved your HTML files inside a folder named docs.

Action: Click Save.

Note: After clicking Save, the deployment is not instantaneous. It triggers a GitHub Action in the background. Wait 30-60 seconds and refresh your page.

Solution 2: The "Missing Index" Pattern

GitHub Pages strictly requires an entry file named index.html (all lowercase).

If your file is named Index.html, home.html, or readme.md (without a Jekyll theme), the server will not serve it as the default page. Linux-based servers (which run GitHub Pages) are case-sensitive.

Ensure your project structure resembles this:

my-portfolio/
├── .git/
├── assets/
│   ├── css/
│   │   └── style.css
│   └── images/
├── index.html  <-- MUST exist and be lowercase
└── readme.md

Valid HTML5 Entry Point

If you are unsure if your code is valid, replace your index.html content with this modern, semantic HTML5 boilerplate to test the connection:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="My Developer Portfolio">
    <title>Deployment Successful</title>
    <style>
        :root {
            --bg-color: #121212;
            --text-color: #e0e0e0;
            --accent: #4caf50;
        }
        body {
            background-color: var(--bg-color);
            color: var(--text-color);
            font-family: system-ui, -apple-system, sans-serif;
            display: grid;
            place-items: center;
            height: 100vh;
            margin: 0;
        }
        h1 {
            border-bottom: 2px solid var(--accent);
            padding-bottom: 0.5rem;
        }
    </style>
</head>
<body>
    <main>
        <h1>Status: Online</h1>
        <p>Your GitHub Pages site is correctly configured.</p>
    </main>
</body>
</html>

Solution 3: Jekyll Configuration (_config.yml)

If you are using Jekyll, a 404 error often stems from a missing or misconfigured baseurl in your _config.yml file.

When not using a custom domain (e.g., you are using username.github.io/repo-name), the browser attempts to load assets from the root domain rather than the repository subfolder.

The Fix

Create or edit the _config.yml file in your root directory. Ensure the baseurl matches your repository name exactly.

# _config.yml

title: "My Portfolio"
description: "A showcase of my software engineering projects"
author: "Dev Name"

# CRITICAL SETTINGS FOR GITHUB PAGES
# Replace 'repo-name' with your actual repository name
# If your repo is username.github.io, leave baseurl empty: ""
baseurl: "/repo-name" 
url: "https://yourusername.github.io"

theme: jekyll-theme-slate

# Build settings
markdown: kramdown
plugins:
  - jekyll-feed
  - jekyll-seo-tag

After updating _config.yml, commit and push the changes. This forces Jekyll to rebuild the site with the correct asset paths.

Advanced: Modern Deployment with GitHub Actions

For a more robust solution used in professional environments, switch from "Deploy from Branch" to GitHub Actions. This gives you granular control over the build process and eliminates "magic" behavior.

  1. Go to Settings > Pages > Build and deployment.
  2. Switch Source to GitHub Actions.
  3. Create a file in your repository at .github/workflows/static.yml.

Paste the following configuration. This explicitly tells GitHub exactly how to upload your files, bypassing the branch guessing logic entirely.

name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Setup Pages
        uses: actions/configure-pages@v4
        
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload entire repository
          path: '.'
          
      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4

Troubleshooting Edge Cases

If you have applied the fixes above and still see a 404:

1. Browser Caching

Browsers aggressively cache 404 responses. If you fixed the issue but still see the error, perform a Hard Refresh:

  • Windows/Linux: Ctrl + F5
  • Mac: Cmd + Shift + R

2. Private Repositories

If you are on the GitHub Free tier, GitHub Pages allows standard deployments only from Public repositories. If your repository is Private, Pages will not publish unless you upgrade to GitHub Pro/Team.

3. The "jekyll-theme" Gem Error

If you are running Jekyll locally and it works, but it fails on GitHub, you might be using a gem that isn't supported by GitHub Pages standard environment. Check the Actions tab in your repository. If you see a red "X" on the build stage, click it to read the logs. You may need to generate a _site folder locally and push that instead of the raw Ruby files.

Conclusion

The "There isn't a GitHub Pages site here" error is rarely a code issue; it is a configuration mismatch. By explicitly defining your source branch (usually main), ensuring your entry point is a lowercase index.html at the root, and using modern GitHub Actions workflows, you ensure the routing layer knows exactly where to find your content.

Labels: