Welcome to LeviFREE's Blog

1. bundler: command not found: jekyll#

Cause: Local dependencies are not fully installed.

Fix:

1
bundle install
2
bundle exec jekyll serve

If you are on a new machine, first verify that Ruby and Bundler are installed.

2. Front Matter Parsing Failure#

Common Error Message:

1
YAML Exception reading ...

High-Frequency Causes:

• --- does not appear in pairs.
• Mixing spaces and tabs for indentation.
• Fields like title contain unescaped special characters.

Suggestions:

• Start checking from the top 30 lines of the reported file.
• Use 2 spaces consistently for indentation.

3. Date Format Causes Article Not to Show#

Cause: Illegal date field format or inconsistent future time policy.

Check:

• Are you using YYYY-MM-DD HH:MM:SS?
• Does the future setting in _config.yml match your expectations?

4. Port Already in Use, Service Fails to Start#

Error Example:

1
Address already in use - bind(2)

Fix:

1
lsof -i :4000
2
kill -9 <PID>
3
bundle exec jekyll serve --port 4001

5. Chinese Paths or Encoding Issues#

In some system environments, non-UTF-8 files cause parsing exceptions.

Recommendations:

• Unify Markdown files to UTF-8.
• Try to use English, numbers, and hyphens for filenames.

6. Plugin Environment Differences (Runs Locally, Fails Online)#

Cause: The local plugins and the set of plugins supported by GitHub Pages are inconsistent.

Handling:

• Prioritize using GitHub Pages whitelisted plugins.
• Or switch to using GitHub Actions to build yourself and publish the _site directory.

7. Liquid Syntax Errors#

Most common in include tags and loops.

Example Issues:

• Tag not closed.
• Variable name misspelled.
• Illegal syntax in conditional checks.

Troubleshooting Tips:

• Start pinpointing from the most recently modified layout file.
• Temporarily comment out suspicious blocks to do a binary search.

8. Asset Path 404#

Often seen with inconsistent baseurl configurations.

Recommendations:

• Construct paths using {{ site.baseurl }} consistently both locally and online.
• Avoid hardcoding absolute paths for images and scripts.

9. Incremental Build Cache Causes “Changes Not Taking Effect”#

Fix:

1
bundle exec jekyll clean
2
bundle exec jekyll serve

10. Dependency Version Conflicts#

Symptom: Suddenly unable to build after updating a gem.

Handling Process:

1. Check changes in Gemfile.lock first.
2. Rollback to the previous working lock version.
3. Upgrade gems in batches, do not upgrade all at once.

A Universal Troubleshooting Process#

1. Look at the first error message; don’t be distracted by subsequent chain-reaction errors.
2. Pinpoint the “most recently modified files” to check first.
3. Restore build capability first, optimize later.

Summary#

The key to Jekyll troubleshooting is having a process, not random guessing. Once you master these 10 high-frequency issues, 90% of build failures can be quickly located.