Jekyll "Liquid Exception" build failure in CI

By Daniel Zoghalchali·Latchkey

Jekyll renders pages through Liquid, and a tag or filter raised an exception. The message names the file and the Liquid construct that failed (an unknown tag, a missing include, or a method called on the wrong type).

What this error means

jekyll build fails with "Liquid Exception: ... in FILE" describing the failing tag or filter, and the build stops.

Liquid Exception: Unknown tag 'highlightt' in _posts/2026-06-01-intro.md
             Error: Run jekyll build --trace for more information

Common causes

An unknown Liquid tag or filter

A typo in a tag name (or a tag from a plugin not installed) makes Liquid raise "Unknown tag".

A missing include or undefined method

An {% include %} of a file that does not exist, or a filter applied to nil, raises a Liquid exception during render.

How to fix it

Run with --trace and fix the construct

1. Re-run jekyll build --trace to see the full backtrace and file.
2. Fix the tag name, restore the missing include, or guard the nil value.
3. Rebuild.

bundle exec jekyll build --trace

Install the plugin that provides the tag

If the tag comes from a plugin, add it to the Gemfile and plugins so Liquid recognizes it.

# Gemfile
gem "jekyll-feed"

How to prevent it

• Use --trace to get the full backtrace for Liquid errors.
• Install plugins that register custom tags or filters.
• Guard filters against nil values in templates.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation