Hugo "Error building site: failed to render pages" in CI

By Daniel Zoghalchali·Latchkey

Hugo rendered the site and a template failed while executing. The wrapped error names the template and the failing expression, commonly a nil value or a method/field that does not exist on the current context.

What this error means

hugo fails with "Error building site: failed to render pages: render of 'page' failed: execute of template failed:" and a Go template error pointing at the layout and line.

Error: error building site: failed to render pages: render of "page" failed:
execute of template failed: template: _default/single.html:12:24: executing
"_default/single.html" at <.Params.author.name>: nil pointer evaluating interface {}.name

Common causes

A nil value dereferenced in a template

The layout accesses a nested field (for example .Params.author.name) that is absent on some pages, so Hugo hits a nil pointer.

A missing method or field on the context

A template calls a field or function that does not exist for the current page type, and execution fails.

How to fix it

Guard nil values with with/default

1. Read the template and line the error names.
2. Wrap the access in with or provide a default so absent values do not deref nil.
3. Rebuild.

{{ with .Params.author }}{{ .name }}{{ end }}

Build with verbose to locate the page

Use verbose logging to see which content file triggered the template failure.

hugo --logLevel info

How to prevent it

• Guard optional front matter with with or default in templates.
• Keep front matter shapes consistent across content.
• Run a full hugo build in CI to catch render failures.

Frequently asked questions

Related guides

References

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