Hexo "Cannot find module" on generate in CI

By Kaveh Alemi·Latchkey

Hexo loads its core, plugins, and theme renderers from node_modules at startup. A missing module - hexo itself, a renderer like hexo-renderer-marked, or a theme dependency - aborts hexo generate.

What this error means

hexo generate fails with "Cannot find module 'hexo'" or "Cannot find module 'hexo-renderer-X'", before any posts are processed.

Error: Cannot find module 'hexo-renderer-pug'
Require stack:
- /home/runner/work/blog/blog/node_modules/hexo/lib/hexo/index.js

Common causes

A plugin or renderer is not in package.json

The theme or config expects a renderer/plugin that was never added as a dependency, so a clean CI install omits it.

Dependencies were not installed before generate

The job ran hexo generate without a prior npm ci, leaving node_modules incomplete.

How to fix it

Install all renderers and plugins

1. Add every plugin and renderer the theme needs to package.json.
2. Run a clean install before generating.
3. Commit the lockfile so CI installs the same set.

npm install hexo-renderer-pug --save
npm ci && npx hexo generate

Vendor the theme dependencies

If the theme is a submodule, install its own dependencies too so its required modules resolve.

- run: git submodule update --init --recursive
- run: npm ci

How to prevent it

• Keep all Hexo plugins and renderers in package.json.
• Initialize theme submodules and install their dependencies.
• Run npm ci before hexo generate.

Frequently asked questions

Related guides

References

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