Zola "Failed to build the site" in CI

Zola prints "Error: Failed to build the site" as the umbrella message, then a "Reason:" line with the actual cause. Read the Reason: a Tera render error, a missing template, or invalid content or config.

What this error means

zola build exits non-zero with "Error: Failed to build the site" followed by an indented "Reason:" explaining what failed.

Error: Failed to build the site
Reason: Failed to render section '/content/_index.md'
Reason: Reason: Variable `section.titel` not found in context while rendering 'index.html'

Common causes

A nested Reason points at the real failure

Zola chains Reason lines; the deepest one (a Tera variable, a template, or a content parse) is the actionable cause.

A content or config problem surfaced at build

Invalid frontmatter, a broken internal link, or a config value the build cannot satisfy triggers the top-level failure.

How to fix it

Read the deepest Reason and fix it there

1. Scroll to the last "Reason:" line; it names the concrete error.
2. Fix that template variable, link, or content issue.
3. Re-run zola build to confirm the chain clears.

zola build

Check the build with --drafts off in CI

Build the same way CI does so the failing Reason reproduces locally.

zola build --base-url "$DEPLOY_URL"

How to prevent it

• Always read the deepest Reason, not the umbrella message.
• Build locally with the same flags as CI.
• Validate frontmatter and internal links before pushing.

Related guides