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.
Liquid template errors: debugging effectively
Liquid template errors are among the most common Jekyll development problems, and they can be cryptic. An error like Liquid Exception: undefined method or Liquid Warning: Liquid syntax error points to a specific file but the root cause may be subtle — a missing variable, an unexpected data type, or a filter applied to the wrong input.
The most effective debugging technique for Liquid errors is isolation: add {{ variable | inspect }} to your template to see exactly what data is available at that point. The inspect filter outputs the full Ruby object representation, including nil values that might be causing unexpected behaviour. If {{ page.author | inspect }} outputs nil, you know the author field is not set on that page, and any filter chain that assumes it is a string will fail.
For complex Liquid logic, comment out blocks progressively until the error disappears — this binary search approach quickly isolates which specific statement is causing the problem. Jekyll’s --verbose flag provides more detailed error messages that include the full template context, which is particularly useful for errors in include files or layout inheritance.
Front matter YAML errors: the silent failures
YAML parsing errors in front matter are particularly insidious because Jekyll’s default behaviour is to log a warning and skip the problematic front matter rather than stopping the build entirely. This means a post with a YAML error may appear to build successfully, but the affected fields will be missing from the output — leading to template conditionals failing silently or navigation entries disappearing.
Enable strict_front_matter: true in your _config.yml to make Jekyll error (and stop the build) on any front matter parsing failure. This surfaces problems immediately rather than letting them propagate silently through your templates.
The most common YAML errors are: unquoted strings containing colons (: is a YAML key-value separator; use title: "Jekyll: A Guide" not title: Jekyll: A Guide); inconsistent indentation (YAML requires consistent spaces, never tabs); and incorrectly typed values (a date field that Jekyll expects as YYYY-MM-DD but is written as December 5, 2025). Running your front matter through an online YAML validator before committing catches these issues before they reach the build.
Asset path errors: the baseurl problem
A significant proportion of “my CSS is missing” and “my images are broken” Jekyll errors trace back to baseurl misconfiguration. The baseurl setting in _config.yml specifies the subdirectory your site lives in — for a GitHub Pages project site at username.github.io/my-project/, the baseurl is /my-project. For a site at a custom domain or at the root of GitHub Pages, the baseurl should be empty (baseurl: "").
The error pattern: a site that works locally with bundle exec jekyll serve but shows broken styles and images when deployed to GitHub Pages. The cause: the local server is at localhost:4000/ (no baseurl), but the deployed site is at username.github.io/my-project/ — and any asset path without the baseurl prefix resolves to the wrong location.
The fix is two-part: set baseurl: "/my-project" in _config.yml for project sites, and use relative_url filter on every internal link and asset path in templates: {{ '/assets/css/main.css' | relative_url }} rather than '/assets/css/main.css'. The relative_url filter prepends the baseurl automatically, ensuring paths work correctly at any deployment root.
Plugin compatibility errors
Jekyll plugins are Ruby gems, and they depend on specific versions of Jekyll, Ruby, and each other. A plugin that worked with Jekyll 4.2 may not work with Jekyll 4.3 due to API changes. A gem that was written for Ruby 2.7 may emit deprecation warnings on Ruby 3.2 or fail on Ruby 3.3. These compatibility issues surface as build failures that are unclear without understanding the dependency chain.
When a plugin update breaks your build, the diagnostic path is: check the plugin’s GitHub repository for recent issues or PRs mentioning the error you are seeing; check whether other plugins in your Gemfile have conflicting version requirements (run bundle update and read the output carefully for resolution conflicts); and check whether your Ruby version is within the plugin’s supported range.
The preventive measure: use bundle exec for all Jekyll commands (it ensures the exact gem versions in Gemfile.lock are used), commit Gemfile.lock to version control (so every developer and deployment uses the same gem versions), and test gem updates in a separate branch before merging to main. Treating your Ruby dependency stack with the same care as any production software dependency prevents the class of “worked yesterday, broken today” failures that plugin updates can introduce.