gohugoio/hugo · error
failed to execute template %s: %w
Error message
failed to execute template %s: %w
What it means
Returned by pageContentOutput.Render when the resolved layout template was found but executing it against the page failed. The underlying template execution error (nil pointer method call, bad function argument, error from a partial, etc.) is wrapped with the template name and the page's file context via wrapError, so the root cause is in the %w-wrapped inner error, not this message.
Source
Thrown at hugolib/page__per_output.go:123
}
func (pco *pageContentOutput) Render(ctx context.Context, layout ...string) (template.HTML, error) {
if len(layout) == 0 {
return "", errors.New("no layout given")
}
templ, found, err := pco.po.p.resolveTemplate(layout...)
if err != nil {
return "", pco.po.p.wrapError(err)
}
if !found {
return "", fmt.Errorf("template %q not found", layout[0])
}
// Make sure to send the *pageState and not the *pageContentOutput to the template.
res, err := executeToString(ctx, pco.po.p.s.GetTemplateStore(), templ, pco.po.p)
if err != nil {
return "", pco.po.p.wrapError(fmt.Errorf("failed to execute template %s: %w", templ.Name(), err))
}
return template.HTML(res), nil
}
func (pco *pageContentOutput) Fragments(ctx context.Context) *tableofcontents.Fragments {
return pco.c().Fragments(ctx)
}
func (pco *pageContentOutput) RenderShortcodes(ctx context.Context) (template.HTML, error) {
return pco.c().RenderShortcodes(ctx)
}
func (pco *pageContentOutput) Markup(opts ...any) page.Markup {
if len(opts) > 1 {
panic("too many arguments, expected 0 or 1")
}
var scope string
if len(opts) == 1 {View on GitHub ↗ (pinned to 8a468df065)
Solutions
- Read the wrapped inner error — it names the exact template line and failure; fix that expression in the named layout file.
- Guard optional data with `with`/`if` in the layout, e.g. `{{ with .Params.image }}...{{ end }}`.
- Reproduce with `hugo -v` or building just the failing section to see the full error chain including file position.
Example fix
<!-- before (layouts/summary.html) -->
<img src="{{ .Params.image.url }}">
<!-- after -->
{{ with .Params.image }}<img src="{{ .url }}">{{ end }} Defensive patterns
Strategy: try-catch
Type guard
var fe herrors.FileError isTemplateErr := errors.As(err, &fe)
Try / catch
// Programmatic embedders: template execution failures surface from the build
if err := b.Build(hugolib.BuildCfg{}); err != nil {
var fe herrors.FileError
if errors.As(err, &fe) {
log.Printf("template error at %s: %v", fe.Position(), fe)
}
return err
} Prevention
- Guard nil-prone accesses in templates with with/if before calling methods on .Params values
- Test templates against pages with minimal front matter — execution errors usually come from missing fields
- Read the file:line position in the wrapped error; it points into the failing template
When it happens
Trigger: `{{ .Render "summary" }}` where summary.html itself errors at execution time — calling a method on a nil value, wrong argument types to template funcs, a failing partial, or an error returned by resources/transform calls inside the layout.
Common situations: Templates assuming params exist (`.Params.foo.bar` on nil), date/format calls on missing fields, partials that error only for certain pages (e.g. pages without images), or upgrades where a template function's signature or behavior changed.
Related errors
- no layout given
- error building site: %w
- failed to detect format from content
- failed to detect target data serialization format
- templates.Defer cannot be used inside a partialCached partia
AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31).
Data as JSON: /data/errors/ccefe1b5e6884424.json.
Report an issue: GitHub ↗.