<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="generator" content="Jekyll v3.4.1">
<link type="application/atom+xml" rel="alternate" href="https://jekyllrb.com/feed.xml" title="Jekyll • Simple, blog-aware, static sites">
<link rel="alternate" type="application/atom+xml" title="Recent commits to Jekyll’s master branch" href="https://github.com/jekyll/jekyll/commits/master.atom">
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900">
<link rel="stylesheet" href="/css/screen.css">
<link rel="icon" type="image/x-icon" href="/favicon.ico">
<!-- Begin Jekyll SEO tag v2.1.0 -->
<title>Troubleshooting - Jekyll • Simple, blog-aware, static sites</title>
<meta property="og:title" content="Troubleshooting">
<meta name="description" content="If you ever run into problems installing or using Jekyll, here are a few tips that might be of help. If the problem you’re experiencing isn’t covered below, please check out our other help resources as well.">
<meta property="og:description" content="If you ever run into problems installing or using Jekyll, here are a few tips that might be of help. If the problem you’re experiencing isn’t covered below, please check out our other help resources as well.">
<link rel="canonical" href="https://jekyllrb.com/docs/troubleshooting/">
<meta property="og:url" content="https://jekyllrb.com/docs/troubleshooting/">
<meta property="og:site_name" content="Jekyll • Simple, blog-aware, static sites">
<meta property="og:type" content="article">
<meta property="article:published_time" content="2017-03-22T08:07:19-07:00">
<meta name="twitter:card" content="summary">
<meta name="twitter:site" content="@jekyllrb">
<meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY">
<script type="application/ld+json">
{"@context": "http://schema.org",
"@type": "BlogPosting",
"headline": "Troubleshooting",
"datePublished": "2017-03-22T08:07:19-07:00",
"description": "If you ever run into problems installing or using Jekyll, here are a few tips that might be of help. If the problem you’re experiencing isn’t covered below, please check out our other help resources as well.",
"publisher": {"@type": "Organization",
"logo": {"@type": "ImageObject",
"url": "https://jekyllrb.com/img/logo-2x.png"}},
"url": "https://jekyllrb.com/docs/troubleshooting/"}</script>
<!-- End Jekyll SEO tag -->
<!--[if lt IE 9]>
<script src="/js/html5shiv.min.js"></script>
<script src="/js/respond.min.js"></script>
<![endif]-->
</head>
<body class="wrap">
<header>
<nav class="mobile-nav show-on-mobiles">
<ul>
<li class="">
<a href="/">Home</a>
</li>
<li class="current">
<a href="/docs/home/">Docs</a>
</li>
<li class="">
<a href="/news/">News</a>
</li>
<li class="">
<a href="/community/">Community</a>
</li>
<li class="">
<a href="/help/">Help</a>
</li>
<li>
<a href="https://github.com/jekyll/jekyll"><span class="hide-on-mobiles">View on </span>GitHub</a>
</li>
</ul>
</nav>
<div class="grid">
<div class="unit one-third center-on-mobiles">
<h1>
<a href="/">
<span class="sr-only">Jekyll</span>
<img src="/img/logo-2x.png" width="249" height="115" alt="Jekyll Logo">
</a>
</h1>
</div>
<nav class="main-nav unit two-thirds hide-on-mobiles">
<ul>
<li class="">
<a href="/">Home</a>
</li>
<li class="current">
<a href="/docs/home/">Docs</a>
</li>
<li class="">
<a href="/news/">News</a>
</li>
<li class="">
<a href="/community/">Community</a>
</li>
<li class="">
<a href="/help/">Help</a>
</li>
<li>
<a href="https://github.com/jekyll/jekyll"><span class="hide-on-mobiles">View on </span>GitHub</a>
</li>
</ul>
</nav>
</div>
</header>
<section class="docs">
<div class="grid">
<div class="docs-nav-mobile unit whole show-on-mobiles">
<select onchange="if (this.value) window.location.href=this.value">
<option value="">Navigate the docs…</option>
<optgroup label="Getting Started">
<option value="/docs/home/">Welcome</option>
<option value="/docs/quickstart/">Quick-start guide</option>
<option value="/docs/installation/">Installation</option>
<option value="/docs/usage/">Basic Usage</option>
<option value="/docs/structure/">Directory structure</option>
<option value="/docs/configuration/">Configuration</option>
</optgroup>
<optgroup label="Your Content">
<option value="/docs/frontmatter/">Front Matter</option>
<option value="/docs/posts/">Writing posts</option>
<option value="/docs/drafts/">Working with drafts</option>
<option value="/docs/pages/">Creating pages</option>
<option value="/docs/static-files/">Static Files</option>
<option value="/docs/variables/">Variables</option>
<option value="/docs/collections/">Collections</option>
<option value="/docs/datafiles/">Data Files</option>
<option value="/docs/assets/">Assets</option>
<option value="/docs/migrations/">Blog migrations</option>
</optgroup>
<optgroup label="Customization">
<option value="/docs/templates/">Templates</option>
<option value="/docs/includes/">Includes</option>
<option value="/docs/permalinks/">Permalinks</option>
<option value="/docs/pagination/">Pagination</option>
<option value="/docs/plugins/">Plugins</option>
<option value="/docs/themes/">Themes</option>
<option value="/docs/extras/">Extras</option>
</optgroup>
<optgroup label="Deployment">
<option value="/docs/github-pages/">GitHub Pages</option>
<option value="/docs/deployment-methods/">Deployment methods</option>
<option value="/docs/continuous-integration/">Continuous Integration</option>
</optgroup>
<optgroup label="Miscellaneous">
<option value="/docs/troubleshooting/">Troubleshooting</option>
<option value="/docs/sites/">Sites using Jekyll</option>
<option value="/docs/resources/">Resources</option>
<option value="/docs/upgrading/0-to-2/">Upgrading from 0.x to 2.x</option>
<option value="/docs/upgrading/2-to-3/">Upgrading from 2.x to 3.x</option>
</optgroup>
<optgroup label="Meta">
<option value="/docs/contributing/">Contributing</option>
<option value="/docs/maintaining/">Maintaining Jekyll</option>
<option value="/docs/conduct/">Code of Conduct</option>
<option value="/docs/history/">History</option>
</optgroup>
</select>
</div>
<div class="unit four-fifths">
<article>
<div class="improve right hide-on-mobiles">
<a href="https://github.com/jekyll/jekyll/edit/master/docs/_docs/troubleshooting.md"><i class="fa fa-pencil"></i> Improve this page</a>
</div>
<h1>Troubleshooting</h1>
<p>If you ever run into problems installing or using Jekyll, here are a few tips
that might be of help. If the problem you’re experiencing isn’t covered below,
<strong>please <a href="/help/">check out our other help resources</a></strong> as well.</p>
<ul>
<li><a href="#installation-problems">Installation Problems</a></li>
<li><a href="#problems-running-jekyll">Problems running Jekyll</a></li>
<li><a href="#base-url-problems">Base-URL Problems</a></li>
<li><a href="#configuration-problems">Configuration problems</a></li>
<li><a href="#markup-problems">Markup Problems</a></li>
<li><a href="#production-problems">Production Problems</a></li>
</ul>
<h2 id="installation-problems">Installation Problems</h2>
<p>If you encounter errors during gem installation, you may need to install
the header files for compiling extension modules for Ruby 2.0.0. This
can be done on Ubuntu or Debian by running:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>sudo apt-get install ruby2.3-dev
</code></pre>
</div>
<p>On Red Hat, CentOS, and Fedora systems you can do this by running:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>sudo yum install ruby-devel
</code></pre>
</div>
<p>If you installed the above - specifically on Fedora 23 - but the extensions would still not compile, you are probably running a Fedora image that misses the <code class="highlighter-rouge">redhat-rpm-config</code> package. To solve this, simply run:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>sudo dnf install redhat-rpm-config
</code></pre>
</div>
<p>On <a href="https://www.nearlyfreespeech.net/">NearlyFreeSpeech</a> you need to run the
following commands before installing Jekyll:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code><span class="nb">export </span><span class="nv">GEM_HOME</span><span class="o">=</span>/home/private/gems
<span class="nb">export </span><span class="nv">GEM_PATH</span><span class="o">=</span>/home/private/gems:/usr/local/lib/ruby/gems/1.8/
<span class="nb">export </span><span class="nv">PATH</span><span class="o">=</span><span class="nv">$PATH</span>:/home/private/gems/bin
<span class="nb">export </span><span class="nv">RB_USER_INSTALL</span><span class="o">=</span><span class="s1">'true'</span>
</code></pre>
</div>
<p>To install RubyGems on Gentoo:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>sudo emerge -av dev-ruby/rubygems
</code></pre>
</div>
<p>On Windows, you may need to install <a href="https://wiki.github.com/oneclick/rubyinstaller/development-kit">RubyInstaller
DevKit</a>.</p>
<p>On macOS, you may need to update RubyGems (using <code class="highlighter-rouge">sudo</code> only if necessary):</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>sudo gem update --system
</code></pre>
</div>
<p>If you still have issues, you can download and install new Command Line
Tools (such as <code class="highlighter-rouge">gcc</code>) using the following command:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>xcode-select --install
</code></pre>
</div>
<p>which may allow you to install native gems using this command (again using
<code class="highlighter-rouge">sudo</code> only if necessary):</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>sudo gem install jekyll
</code></pre>
</div>
<p>Note that upgrading macOS does not automatically upgrade Xcode itself
(that can be done separately via the App Store), and having an out-of-date
Xcode.app can interfere with the command line tools downloaded above. If
you run into this issue, upgrade Xcode and install the upgraded Command
Line Tools.</p>
<h3 id="jekyll--mac-os-x-1011">Jekyll & Mac OS X 10.11</h3>
<p>With the introduction of System Integrity Protection, several directories
that were previously writable are now considered system locations and are no
longer available. Given these changes, there are a couple of simple ways to get
up and running. One option is to change the location where the gem will be
installed (again using <code class="highlighter-rouge">sudo</code> only if necessary):</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>sudo gem install -n /usr/local/bin jekyll
</code></pre>
</div>
<p>Alternatively, Homebrew can be installed and used to set up Ruby. This can be
done as follows:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>ruby -e <span class="s2">"</span><span class="k">$(</span>curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install<span class="k">)</span><span class="s2">"</span>
</code></pre>
</div>
<p>Once Homebrew is installed, the second step is easy:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>brew install ruby
</code></pre>
</div>
<p>Advanced users (with more complex needs) may find it helpful to choose one of a
number of Ruby version managers (<a href="https://rvm.io">RVM</a>, <a href="http://rbenv.org">rbenv</a>, <a href="https://github.com/postmodern/chruby">chruby</a>, <a href="https://github.com/rvm/rvm/blob/master/docs/alt.md">etc</a>.) in
which to install Jekyll.</p>
<p>If you elect to use one of the above methods to install Ruby, it might be
necessary to modify your <code class="highlighter-rouge">$PATH</code> variable using the following command:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code><span class="nb">export </span><span class="nv">PATH</span><span class="o">=</span>/usr/local/bin:<span class="nv">$PATH</span>
</code></pre>
</div>
<p>GUI apps can modify the <code class="highlighter-rouge">$PATH</code> as follows:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>launchctl setenv PATH <span class="s2">"/usr/local/bin:</span><span class="nv">$PATH</span><span class="s2">"</span>
</code></pre>
</div>
<p>Either of these approaches are useful because <code class="highlighter-rouge">/usr/local</code> is considered a
“safe” location on systems which have SIP enabled, they avoid potential
conflicts with the version of Ruby included by Apple, and it keeps Jekyll and
its dependencies in a sandboxed environment. This also has the added
benefit of not requiring <code class="highlighter-rouge">sudo</code> when you want to add or remove a gem.</p>
<h3 id="could-not-find-a-javascript-runtime-execjsruntimeunavailable">Could not find a JavaScript runtime. (ExecJS::RuntimeUnavailable)</h3>
<p>This error can occur during the installation of <code class="highlighter-rouge">jekyll-coffeescript</code> when
you don’t have a proper JavaScript runtime. To solve this, either install
<code class="highlighter-rouge">execjs</code> and <code class="highlighter-rouge">therubyracer</code> gems, or install <code class="highlighter-rouge">nodejs</code>. Check out
<a href="https://github.com/jekyll/jekyll/issues/2327">issue #2327</a> for more info.</p>
<h2 id="problems-running-jekyll">Problems running Jekyll</h2>
<p>On Debian or Ubuntu, you may need to add <code class="highlighter-rouge">/var/lib/gems/1.8/bin/</code> to your path
in order to have the <code class="highlighter-rouge">jekyll</code> executable be available in your Terminal.</p>
<h2 id="base-url-problems">Base-URL Problems</h2>
<p>If you are using base-url option like:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>jekyll serve --baseurl <span class="s1">'/blog'</span>
</code></pre>
</div>
<p>… then make sure that you access the site at:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>http://localhost:4000/blog/index.html
</code></pre>
</div>
<p>It won’t work to just access:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code>http://localhost:4000/blog
</code></pre>
</div>
<h2 id="configuration-problems">Configuration problems</h2>
<p>The order of precedence for conflicting <a href="../configuration/">configuration settings</a>
is as follows:</p>
<ol>
<li>Command-line flags</li>
<li>Configuration file settings</li>
<li>Defaults</li>
</ol>
<p>That is: defaults are overridden by options specified in <code class="highlighter-rouge">_config.yml</code>,
and flags specified at the command-line will override all other settings
specified elsewhere.</p>
<p>If you encounter an error in building the site, with the error message
“‘0000-00-00-welcome-to-jekyll.markdown.erb’ does not have a valid date in the
YAML front matter.” try including the line <code class="highlighter-rouge">exclude: [vendor]</code>
in <code class="highlighter-rouge">_config.yml</code>.</p>
<h2 id="markup-problems">Markup Problems</h2>
<p>The various markup engines that Jekyll uses may have some issues. This
page will document them to help others who may run into the same
problems.</p>
<h3 id="liquid">Liquid</h3>
<p>The latest version, version 2.0, seems to break the use of <code class="highlighter-rouge"><span class="p">{</span><span class="err">{</span></code> in
templates. Unlike previous versions, using <code class="highlighter-rouge"><span class="p">{</span><span class="err">{</span></code> in 2.0 triggers the
following error:</p>
<div class="language-sh highlighter-rouge">
<pre class="highlight"><code><span class="s1">'{{'</span> was not properly terminated with regexp: /<span class="se">\}\}</span>/ <span class="o">(</span>Liquid::SyntaxError<span class="o">)</span>
</code></pre>
</div>
<h3 id="excerpts">Excerpts</h3>
<p>Since v1.0.0, Jekyll has had automatically-generated post excerpts. Since
v1.1.0, Jekyll also passes these excerpts through Liquid, which can cause
strange errors where references don’t exist or a tag hasn’t been closed. If you
run into these errors, try setting <code class="highlighter-rouge">excerpt_separator: ""</code> in your
<code class="highlighter-rouge">_config.yml</code>, or set it to some nonsense string.</p>
<h2 id="production-problems">Production Problems</h2>
<p>If you run into an issue that a static file can’t be found in your
production environment during build since v3.2.0 you should set your
<a href="../configuration/#specifying-a-jekyll-environment-at-build-time">environment to <code class="highlighter-rouge">production</code></a>.
The issue is caused by trying to copy a non-existing symlink.</p>
<div class="note">
<h5>Please report issues you encounter!</h5>
<p>
If you come across a bug, please <a href="https://github.com/jekyll/jekyll-help/issues/new">create an issue</a>
on GitHub describing the problem and any work-arounds you find so we can
document it here for others.
</p>
</div>
<div class="section-nav">
<div class="left align-right">
<a href="/docs/continuous-integration/" class="prev">Back</a>
</div>
<div class="right align-left">
<a href="/docs/sites/" class="next">Next</a>
</div>
</div>
<div class="clear"></div>
</article>
</div>
<div class="unit one-fifth hide-on-mobiles">
<aside>
<h4>Getting Started</h4>
<ul>
<li class=""><a href="/docs/home/">Welcome</a></li>
<li class=""><a href="/docs/quickstart/">Quick-start guide</a></li>
<li class=""><a href="/docs/installation/">Installation</a></li>
<li class=""><a href="/docs/usage/">Basic Usage</a></li>
<li class=""><a href="/docs/structure/">Directory structure</a></li>
<li class=""><a href="/docs/configuration/">Configuration</a></li>
</ul>
<h4>Your Content</h4>
<ul>
<li class=""><a href="/docs/frontmatter/">Front Matter</a></li>
<li class=""><a href="/docs/posts/">Writing posts</a></li>
<li class=""><a href="/docs/drafts/">Working with drafts</a></li>
<li class=""><a href="/docs/pages/">Creating pages</a></li>
<li class=""><a href="/docs/static-files/">Static Files</a></li>
<li class=""><a href="/docs/variables/">Variables</a></li>
<li class=""><a href="/docs/collections/">Collections</a></li>
<li class=""><a href="/docs/datafiles/">Data Files</a></li>
<li class=""><a href="/docs/assets/">Assets</a></li>
<li class=""><a href="/docs/migrations/">Blog migrations</a></li>
</ul>
<h4>Customization</h4>
<ul>
<li class=""><a href="/docs/templates/">Templates</a></li>
<li class=""><a href="/docs/includes/">Includes</a></li>
<li class=""><a href="/docs/permalinks/">Permalinks</a></li>
<li class=""><a href="/docs/pagination/">Pagination</a></li>
<li class=""><a href="/docs/plugins/">Plugins</a></li>
<li class=""><a href="/docs/themes/">Themes</a></li>
<li class=""><a href="/docs/extras/">Extras</a></li>
</ul>
<h4>Deployment</h4>
<ul>
<li class=""><a href="/docs/github-pages/">GitHub Pages</a></li>
<li class=""><a href="/docs/deployment-methods/">Deployment methods</a></li>
<li class=""><a href="/docs/continuous-integration/">Continuous Integration</a></li>
</ul>
<h4>Miscellaneous</h4>
<ul>
<li class="current"><a href="/docs/troubleshooting/">Troubleshooting</a></li>
<li class=""><a href="/docs/sites/">Sites using Jekyll</a></li>
<li class=""><a href="/docs/resources/">Resources</a></li>
<li class=""><a href="/docs/upgrading/0-to-2/">Upgrading from 0.x to 2.x</a></li>
<li class=""><a href="/docs/upgrading/2-to-3/">Upgrading from 2.x to 3.x</a></li>
</ul>
<h4>Meta</h4>
<ul>
<li class=""><a href="/docs/contributing/">Contributing</a></li>
<li class=""><a href="/docs/maintaining/">Maintaining Jekyll</a></li>
<li class=""><a href="/docs/conduct/">Code of Conduct</a></li>
<li class=""><a href="/docs/history/">History</a></li>
</ul>
</aside>
</div>
<div class="clear"></div>
</div>
</section>
<footer>
<div class="grid">
<div class="unit one-third center-on-mobiles">
<p>The contents of this website are <br>© 2017 under the terms of the <a href="https://github.com/jekyll/jekyll/blob/master/LICENSE">MIT License</a>.</p>
</div>
<div class="unit two-thirds align-right center-on-mobiles">
<p>
Proudly hosted by
<a href="https://github.com">
<img src="/img/footer-logo.png" width="100" height="30" alt="GitHub • Social coding">
</a>
</p>
</div>
</div>
</footer>
<script>
var anchorForId = function (id) {
var anchor = document.createElement("a");
anchor.className = "header-link";
anchor.href = "#" + id;
anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>";
anchor.title = "Permalink";
return anchor;
};
var linkifyAnchors = function (level, containingElement) {
var headers = containingElement.getElementsByTagName("h" + level);
for (var h = 0; h < headers.length; h++) {
var header = headers[h];
if (typeof header.id !== "undefined" && header.id !== "") {
header.appendChild(anchorForId(header.id));
}
}
};
document.onreadystatechange = function () {
if (this.readyState === "complete") {
var contentBlock = document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0];
if (!contentBlock) {
return;
}
for (var level = 1; level <= 6; level++) {
linkifyAnchors(level, contentBlock);
}
}
};
</script>
<!-- Gauges (http://get.gaug.es/) -->
<script>
var _gauges = _gauges || [];
(function() {
var t = document.createElement('script');
t.type = 'text/javascript';
t.async = true;
t.id = 'gauges-tracker';
t.setAttribute('data-site-id', '503c5af6613f5d0f19000027');
t.src = '//secure.gaug.es/track.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(t, s);
})();
</script>
<!-- Google Analytics (https://www.google.com/analytics) -->
<script>
!function(j,e,k,y,l,L){j.GoogleAnalyticsObject=y,j[y]||(j[y]=function(){
(j[y].q=j[y].q||[]).push(arguments)}),j[y].l=+new Date,l=e.createElement(k),
L=e.getElementsByTagName(k)[0],l.src='//www.google-analytics.com/analytics.js',
L.parentNode.insertBefore(l,L)}(window,document,'script','ga');
ga('create', 'UA-50755011-1', 'jekyllrb.com');
ga('send', 'pageview');
</script>
</body>
</html>