gohugoio/hugo · error

render of failed

Error message

render of %q failed: %w

What it means

Executing a layout template for a page or output format failed. site.renderForTemplate calls GetTemplateStore().ExecuteWithContext (site.go:1747) and, on error, wraps it with the page/render target name via %w. The underlying cause is a Go template runtime error inside the layout.

Solutions

1. Inspect the wrapped error after 'render of "..." failed:' to get the precise template/runtime cause.
2. Open the named layout and find the offending call (the error usually names the function or line).
3. Add defensive {{ with }}/{{ if }} guards around optional values and conditional output-format branches.
4. Confirm all referenced partials exist and the template uses Hugo's current API.

Example fix

// before (layout)
<title>{{ .Title }} - {{ .Site.Params.brand.name }}</title>

// after
<title>{{ .Title }}{{ with .Site.Params.brand }} - {{ .name }}{{ end }}</title>

// Layouts run inside Hugo's render pipeline; use {{ with }} guards and errorf.
{{ with .Site.Params.brand }}
  <title>{{ $.Title }} - {{ .name }}</title>
{{ else }}
  {{ errorf "layout %q: .Site.Params.brand not configured" $.Layout }}
{{ end }}

When it happens

Trigger: A layout (e.g. layouts/page.html, layouts/_default/list.html) calls a function/method that errors: nil dereference, undefined function, wrong argument types, or a partial that itself errors. The %q filename is the page path when d is a *pageState, otherwise the layout name.

Common situations: Upgrading Hugo and using a removed/renamed template function; a layout referencing .Site.Data fields that no longer exist after a content restructure; a partial missing; output-format-specific layout calling an unsupported method.

Related errors

• failed to process shortcode
• no compatible template found for shortcode
• no layout given
• resources.PostProcess cannot be used in a deferred template
• argument must be a slice

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/13435823de3f40e6. Report an issue: GitHub.

Appendix: source

Thrown at hugolib/site.go:1752

	return false
}

func (s *Site) renderForTemplate(ctx context.Context, name, outputFormat string, d any, w io.Writer, templ *tplimpl.TemplInfo) (err error) {
	if templ == nil {
		s.logMissingLayout(name, "", "", outputFormat)
		return nil
	}

	if ctx == nil {
		panic("nil context")
	}

	if err = s.GetTemplateStore().ExecuteWithContext(ctx, templ, w, d); err != nil {
		filename := name
		if p, ok := d.(*pageState); ok {
			filename = p.String()
		}
		return fmt.Errorf("render of %q failed: %w", filename, err)
	}
	return
}

func (s *Site) shouldBuild(p page.Page) bool {
	if !s.conf.IsKindEnabled(p.Kind()) {
		return false
	}
	return shouldBuild(s.Conf.BuildFuture(), s.Conf.BuildExpired(),
		s.Conf.BuildDrafts(), p.Draft(), p.PublishDate(), p.ExpiryDate())
}

func shouldBuild(buildFuture bool, buildExpired bool, buildDrafts bool, Draft bool,
	publishDate time.Time, expiryDate time.Time,
) bool {
	if !(buildDrafts || !Draft) {
		return false
	}

View on GitHub (pinned to 52c9bd7908)