Jekyll 404 Page Not Working Fix

Q: ### Where should I place my 404 page in Jekyll?

Place `404.md` or `404.html` in your site's root directory. Add `permalink: /404.html` to ensure it is generated at the correct URL. ### Why does my 404 page work locally but not on GitHub Pages? GitHub Pages requires the file to be at the root of the published directory with the exact path `/404.html`. Check that the file is not in a subdirectory. ### Can I customize the 404 page for different environments? Yes. Use Liquid conditionals with `jekyll.environment` to show different content for development and production. `{% if jekyll.environment == "production" %}`.

DodaTech Updated 2026-06-24 2 min read

In this tutorial, you'll learn about Jekyll 404 Page Not Working Fix. We cover key concepts, practical examples, and best practices.

The Problem

Creating a 404.html file but GitHub Pages shows the default Nginx 404 page instead of your custom one.

Wrong

404.html

Created as a standalone HTML file with no frontmatter:

<html>
<head><title>404</title></head>
<body><h1>Page Not Found</h1></body>
</html>

GitHub Pages ignores this file and shows its own 404 page.

Right

Create 404.html with frontmatter and include site.url references:

---
layout: default
permalink: /404.html
---

<h1>404 — Page Not Found</h1>
<p>The page you are looking for does not exist.</p>
<a href="{{ site.url }}">Return Home</a>

Or use a permalink in any markdown file:

---
layout: default
permalink: /404.html
---

Create a `404.md` file in the root of your Jekyll site with `permalink: /404.html` in the frontmatter. GitHub Pages automatically uses this file for 404 responses.

## Prevention

- Set `permalink: /404.html` in the frontmatter
- Use your site's layout template for consistent styling
- Test on local server by visiting a non-existent URL like `/nonexistent`


## Common Mistakes with 404 page

1. **Using `foldl` instead of `foldl'` causing stack overflow on large lists**
2. **Forgetting `deriving (Show, Eq)` on custom data types needed for debugging**
3. **Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable**

These mistakes appear frequently in real-world JEKYLL code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

## Practice Exercise

**Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.**

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

## FAQ

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">### Where should I place my 404 page in Jekyll?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Place <code>404.md</code> or <code>404.html</code> in your site's root directory. Add <code>permalink: /404.html</code> to ensure it is generated at the correct URL.</p>
<h3 id="why-does-my-404-page-work-locally-but-not-on-github-pages">Why does my 404 page work locally but not on GitHub Pages?</h3><p>GitHub Pages requires the file to be at the root of the published directory with the exact path <code>/404.html</code>. Check that the file is not in a subdirectory.</p>
<h3 id="can-i-customize-the-404-page-for-different-environments">Can I customize the 404 page for different environments?</h3><p>Yes. Use Liquid conditionals with <code>jekyll.environment</code> to show different content for development and production. <code>{% if jekyll.environment == &quot;production&quot; %}</code>.</p>
</div></details>

← Previous How to Fix JavaScript TypeError: Cannot read properties of undefined Next → Jekyll Build Error Fix

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Quick Fix