Zola "Couldn't find template" in CI

By Kaveh Alemi·Latchkey

Zola resolves each page to a template by its template frontmatter, section type, or theme. When the named template file is absent from the templates directory (or theme), the build fails.

What this error means

zola build fails with "Reason: Couldn't find template 'X.html'", usually after setting a custom template = in frontmatter or using a theme that lacks it.

Error: Failed to build the site
Reason: Couldn't find template 'custom-page.html'

Common causes

The referenced template file does not exist

Frontmatter sets template = "custom-page.html" but no such file is in templates/ (or the theme's templates/).

The theme was not initialized in CI

A theme provides the template but the theme directory (often a submodule) was not checked out, so the file is missing.

How to fix it

Create or correct the template reference

1. Confirm the template name in frontmatter matches a real file in templates/.
2. Create the missing template or fix the name.
3. Re-run zola build.

+++
template = "page.html"
+++

Initialize the theme submodule

Check out the theme so its templates are present during the build.

- run: git submodule update --init --recursive
- run: zola build

How to prevent it

• Reference only template files that exist in templates/ or the theme.
• Initialize theme submodules before building.
• Keep custom template = frontmatter in sync with real files.

Frequently asked questions

Related guides

References

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