Track and Analyze 404 Errors on GitHub Pages

Why Tracking 404 Errors Matters

Custom 404 pages are only part of the solution. To truly enhance user experience and reduce dead ends, you need to understand how often they occur and why. By tracking 404 errors in your Jekyll site hosted on GitHub Pages, you can identify broken links, outdated references, or misconfigured routes.

The Risk of Ignoring 404 Traffic

• Wasted SEO equity from incoming links
• Decreased trust if users consistently find broken paths
• Hard-to-detect content removals or permalink changes

Challenges with GitHub Pages

Unlike dynamic platforms, GitHub Pages doesn’t support server-side logging. That means traditional log-based 404 error tracking isn’t possible. But there are client-side alternatives that are still effective when paired with custom 404 pages.

Using Google Analytics for 404 Tracking

The easiest way to track 404 hits is through Google Analytics. The custom 404 page can trigger a virtual pageview or event when it’s loaded.

Steps to Set It Up

1. Ensure your 404.html contains your Google Analytics tracking snippet
2. Use JavaScript to fire a virtual pageview or event with a unique identifier like /404.html?page=missing-url

Example Script

<script>
  const path = window.location.pathname + window.location.search;
  gtag('event', 'page_view', {
    page_path: '/404.html?page=' + path,
    page_title: '404 Not Found'
  });
</script>

This helps you identify which URLs are triggering 404s inside your GA dashboard.

Tracking with Plausible or Fathom

If you use privacy-focused analytics platforms like Plausible or Fathom, you can use similar JavaScript-based tracking on the 404.html page:

Plausible Example

<script>
  plausible('404-error', { props: { path: window.location.pathname } });
</script>

This event will show up in your Plausible dashboard and help you identify recurring problem areas.

Visualizing Error Paths with Tags and Filters

Whether you're using GA4, Plausible, or Matomo, tag your 404s with consistent naming so you can filter them later. Use UTM parameters if needed to trace traffic sources.

Filter by Referrer

• Find broken backlinks from external sources
• Identify typos from referring domains
• Spot legacy links from shared content or social posts

Monitoring Internal Links

Sometimes the cause of a 404 is within your own site. Use tools like:

• markdown-link-check for broken links in markdown
• hyperlink to validate HTML and internal navigation

Use GitHub Actions for Link Checking

Automate broken link detection with GitHub Actions workflows. For example, run a link-checker on every push to main branch:

Sample Workflow

name: Link Checker
on:
  push:
    branches: [ main ]

jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Check links
        run: |
          pip install linkchecker
          linkchecker ./_site --ignore-url=https://example.com

This CI/CD approach catches issues before deployment and ensures your published content stays intact.

Tracking Navigation Failures with Search Queries

If you have search enabled in your 404 page, you can log what users search for after hitting a dead link. This can offer additional clues on what they hoped to find.

Implement Search Query Logging

Pair your JavaScript search box with event tracking:

<input id="search-box" type="text">
<button onclick="logSearch()">Search</button>
<script>
  function logSearch() {
    const query = document.getElementById('search-box').value;
    gtag('event', '404_search', { search_term: query });
  }
</script>

Responding to Insights

Once you've tracked the most common broken URLs or patterns, prioritize fixes:

• Set up redirects in _redirects if using Netlify or Cloudflare
• Correct internal links or permalinks
• Update removed content with replacements
• Reach out to external site owners for high-traffic dead backlinks

Turn 404 Reports into a Sitemap Opportunity

If you notice consistent search behavior or repeated attempts to access certain types of content, use that data to inform content creation or navigation structure.

For Example

• Many broken requests for /ebooks? Add an ebook landing page.
• Frequent hits on outdated blog slugs? Add aliases or redirects.

Conclusion

Tracking 404s on Jekyll and GitHub Pages may require some creative workarounds, but the payoff is worth it. Understanding where users get lost allows you to fix issues at the root—improving SEO, retention, and experience sitewide. With analytics, automated checking, and actionable data, your 404 page can become a goldmine of insights instead of a blind spot.