25 Common Jekyll Errors and How to Fix Them Fast
Running into Jekyll build errors? This guide covers the 25 most common Jekyll errors with exact fixes — from dependency issues to Liquid syntax crashes.
Jekyll errors can stop your build dead in its tracks. Whether you are setting up for the first time or have been running Jekyll for years, these errors show up repeatedly. This guide covers the 25 most common ones — with exact error messages and step-by-step fixes.
Dependency and Installation Errors
1. bundler: command not found
Full error:
bundler: command not found: jekyll
Fix: Jekyll runs through Bundler. You need both installed:
gem install bundler jekyll
If you already have them and still see this, run:
bundle exec jekyll serve
Always use bundle exec to ensure Jekyll runs in the context of your project’s gems.
2. Could not find gem 'jekyll (~> 4.0)'
Fix: Run bundle install in your project directory:
bundle install
If the error persists, check your Gemfile includes:
gem "jekyll", "~> 4.0"
3. Gem::FilePermissionError
Full error:
You don't have write permissions for the /usr/bin directory.
Fix: Never install gems with sudo. Instead, use a user-level gem path:
echo 'export GEM_HOME="$HOME/.gem"' >> ~/.bashrc
echo 'export PATH="$HOME/.gem/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
gem install bundler jekyll
4. LoadError: cannot load such file -- webrick
This happens in Ruby 3.0+ where WEBrick was removed from the standard library.
Fix: Add WEBrick to your Gemfile:
gem "webrick"
Then run bundle install.
5. Liquid Exception: No such file or directory @ rb_sysopen
Fix: Check that all files referenced in your _config.yml (like favicon, logo, or custom include files) actually exist at the paths you specified.
Build and Configuration Errors
6. Configuration file: none
Jekyll cannot find _config.yml. This usually means you are running Jekyll from the wrong directory.
Fix: cd into your project’s root folder (where _config.yml lives) before running:
cd my-jekyll-site
bundle exec jekyll serve
7. Invalid date '': (Post)
A post has an empty or malformed date: field in its front matter.
Fix: Check your post’s front matter:
---
date: 2026-06-11
---
Also make sure your filename follows the YYYY-MM-DD-title.md pattern.
8. 'layout' key in front matter defaults is not a string
Fix: Ensure layout values in _config.yml are quoted strings:
defaults:
- scope:
path: ""
type: "posts"
values:
layout: "post" # must be a quoted string
9. Build Warning: Layout 'post' requested in _posts/... does not exist
Fix: Make sure you have a _layouts/post.html file. If you are using a gem-based theme, run:
bundle info --path your-theme-name
This shows you all the files the theme provides. If post.html is missing from your local _layouts/ folder, the theme should provide it.
10. Conflict: The following destination is shared by multiple files
Two files are trying to write to the same output path.
Fix: Check for duplicate slugs — for example, about.md and about/index.md both produce /about/. Remove or rename one of them.
Liquid Template Errors
11. Liquid Exception: Liquid syntax error: Unknown tag 'xyz'
An unrecognised Liquid tag is in your template.
Fix: Either you have a typo, the plugin providing that tag is not installed, or it is not listed in your Gemfile. Check the plugin documentation and add it:
gem "jekyll-plugin-name"
Then add it to _config.yml:
plugins:
- jekyll-plugin-name
12. Liquid Warning: Liquid syntax error (line X): Variable '{{' was not properly terminated
A Liquid tag is malformed — often a missing }} or %}.
Fix: Find line X in the file mentioned and check for unclosed tags. A common mistake:
# Wrong
{{ page.title }
# Right
{{ page.title }}
13. Liquid Exception: undefined method 'to_liquid'
An object is being passed to Liquid that it cannot serialise.
Fix: This often happens with custom plugins. Check that your plugin’s return values are standard Ruby types (strings, arrays, hashes) that Liquid can handle.
14. Liquid::ArgumentError: wrong number of arguments
A Liquid filter is being called with the wrong number of arguments.
Fix: Check the filter documentation. For example, slice takes two arguments:
{{ "Jekyll" | slice: 0, 3 }} # correct
Front Matter Errors
15. YAML Exception reading _posts/...: did not find expected key
Invalid YAML in your post’s front matter.
Fix: YAML is whitespace-sensitive. Common mistakes:
# Wrong — tab indentation
tags:
- jekyll
# Right — space indentation
tags:
- jekyll
Use a YAML validator like yaml-online-parser.appspot.com to check your front matter.
16. Error: invalid byte sequence in UTF-8
A file contains characters that are not valid UTF-8.
Fix: Open the file in a text editor that shows encoding (VS Code, Sublime Text). Save the file as UTF-8. You can also run:
file -i your-file.md
to check the detected encoding.
17. Front matter not being parsed (content appearing as raw ---)
Jekyll only parses front matter if the file starts with --- on the very first line, with no space or BOM character before it.
Fix: Open the file and delete any blank lines before the opening ---. If the file was created on Windows, check for a BOM character using:
hexdump -C your-file.md | head
GitHub Pages Specific Errors
18. Page build failed: unknown tag 'some_tag'
GitHub Pages only supports a subset of Jekyll plugins. A plugin you are using locally is not allowed on GitHub Pages.
Fix: Either use only the allowed plugins, or switch to deploying via GitHub Actions where you can use any plugin.
19. GitHub Pages: Your site is having problems building: The value 'X' was passed to a date filter that cannot be parsed as a date
A date field in your content is malformed.
Fix: Find the file and fix the date:
date: 2026-06-11 # ISO format only, no quotes needed
20. Site deploys but shows old content
GitHub Pages can cache aggressively.
Fix: Hard refresh (Ctrl+Shift+R or Cmd+Shift+R). If the problem persists for more than 10 minutes, check the Actions tab in your GitHub repo for build errors.
Asset and URL Errors
21. CSS/JS not loading on live site (works locally)
Usually a baseurl misconfiguration.
Fix: In _config.yml, set:
url: "https://yourdomain.com"
baseurl: "" # leave empty unless site lives in a subdirectory
For a GitHub Pages project site (e.g. username.github.io/project), set:
baseurl: "/project"
22. Images 404 on live site
Fix: Always use {{ site.baseurl }}/assets/images/photo.jpg in your templates rather than /assets/images/photo.jpg. The baseurl prefix is needed for project sites.
23. Error: ENOENT: no such file or directory, scandir '...'
A directory referenced in _config.yml (like collections_dir) does not exist.
Fix: Create the missing directory:
mkdir -p _collections
Or correct the path in _config.yml.
Server and Watch Errors
24. Address already in use - bind(2) for 127.0.0.1:4000
Another process is using port 4000 (usually a previous Jekyll instance that didn’t shut down cleanly).
Fix: Kill the other process:
lsof -ti:4000 | xargs kill -9
Or run Jekyll on a different port:
bundle exec jekyll serve --port 4001
25. --watch not detecting changes
Jekyll’s file watcher sometimes misses changes, especially on case-insensitive filesystems (macOS) or inside Docker containers.
Fix: Use the --force-polling flag:
bundle exec jekyll serve --livereload --force-polling
Quick Reference: Most Common Fixes
| Symptom | Most likely fix |
|---|---|
command not found |
gem install bundler jekyll |
| Build fails silently | Run bundle exec jekyll build --trace for full error output |
| Local works, GitHub Pages fails | Check allowed plugins list |
| CSS not loading | Fix baseurl in _config.yml |
| YAML errors | Validate front matter with a YAML linter |
| Port 4000 in use | lsof -ti:4000 | xargs kill -9 |
Still stuck?
Run Jekyll with full trace output to get the most helpful error message:
bundle exec jekyll build --trace
This prints the complete stack trace and usually points directly to the file and line causing the problem.
Browse Jekyll themes on JekyllHub to start fresh with a well-tested, error-free base.