gohugoio/hugo · error

render of %q failed: %w

Error message

render of %q failed: %w

What it means

Wrapped by Site.renderForTemplate (hugolib/site.go:1752) when executing a layout template for a page or standalone output (sitemap, RSS, 404, etc.) fails. The %q is the page path or template name, and %w carries the actual template execution error. Note that a nil template is not this error — that's silently logged as a missing layout.

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 8a468df065)

Solutions

1. Inspect the wrapped error — it identifies the template file and line of the real failure.
2. Guard optional params/resources in the template with `with`/`if` before dereferencing.
3. If the failing name is a specific page, compare its front matter to pages that render fine.
4. After a Hugo upgrade, update the theme or check release notes for removed template APIs.

Example fix

// before (layouts/page.html)
{{ .Params.author.name }}
// after
{{ with .Params.author }}{{ .name }}{{ end }}

if err := site.Build(...); err != nil {
    // "render of %q failed: %w" — unwrap to find the template error
    var te *herrors.ErrorContext
    log.Printf("render failed: %v", err)
    // do not publish partial output; fail the deploy
    return err
}

When it happens

Trigger: ExecuteWithContext failing on any layout render: layouts/page.html, layouts/list.html, taxonomy/term templates, sitemap/robots/404 renders — due to template runtime errors (nil pointer method calls, failing template funcs, errorf calls, bad .Params access).

Common situations: Theme templates broken by a Hugo upgrade (removed methods like .Site.Author), templates assuming site/page params that a given page lacks, partial or render-hook errors bubbling up, or data files missing keys the template indexes into.

Related errors

• failed to render shortcode %q: %w
• no alias template found
• quality ranges from 1 to 100 inclusive
• invalid image dimensions
• must provide Width and Height

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/13435823de3f40e6.json. Report an issue: GitHub ↗.