In case you’re experiencing problems with using Hexo, here is a list of solutions to some frequently encountered issues. If this page doesn’t help you solve your problem, try doing a search on GitHub or our Google Group.

YAML Parsing Error

JS-YAML: incomplete explicit mapping pair; a key node is missed at line 18, column 29:
      last_updated: Last updated: %s

Wrap the string with quotations if it contains colons.

JS-YAML: bad indentation of a mapping entry at line 18, column 31:
      last_updated:"Last updated: %s"

Make sure you are using soft tabs and add a space after colons.

You can see YAML Spec for more info.


Error: EMFILE, too many open files

Though Node.js has non-blocking I/O, the maximum number of synchronous I/O is still limited by the system. You may come across an EMFILE error when trying to generate a large number of files. You can try to run the following command to increase the number of allowed synchronous I/O operations.

$ ulimit -n 10000

Git Deployment Problems

fatal: '' does not appear to be a git repository

Make sure you have set up git on your computer or try to use HTTPS repository URL instead.

Server Problems

Error: listen EADDRINUSE

You may have started two Hexo servers at the same time or there might be another application using the same port. Try to modify the port setting or start the Hexo server with the -p flag.

$ hexo server -p 5000

Plugin Installation Problems

npm ERR! node-waf configure build

This error may occur when trying to install a plugin written in C, C++ or another non-JavaScript language. Make sure you have installed the right compiler on your computer.

Error with DTrace (Mac OS X)

{ [Error: Cannot find module './build/Release/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' }
{ [Error: Cannot find module './build/default/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' }
{ [Error: Cannot find module './build/Debug/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' }

DTrace install may have issue, use this:

$ npm install hexo --no-optional

See #1326

Iterate Data Model on Jade or Swig

Hexo uses Warehouse for its data model. It’s not an array so you may have to transform objects into iterables.

{% for post in site.posts.toArray() %}
{% endfor %}

Data Not Updated

Some data cannot be updated, or the newly generated files are identical to those of the last version. Clean the cache and try again.

$ hexo clean

Escape Contents

Hexo uses Nunjucks to render posts (Swig was used in older version, which share a similar syntax). Content wrapped with {{ }} or {% %} will get parsed and may cause problems. You can wrap sensitive content with the raw tag plugin.

{% raw %}
Hello {{ sensitive }}
{% endraw %}