gohugoio/hugo · error

renderDeferred: %w

Error message

renderDeferred: %w

What it means

Sent via SendError when renderDeferred() fails. Deferred rendering handles content marked with the deferred render hook (e.g. RenderShortcodes / render-code blocks resolved after the main render). The %w is the deferred-render error.

Source

Thrown at hugolib/hugo_sites_build.go:213

	if prepareErr == nil {
		if err := h.render(infol, conf); err != nil {
			h.SendError(fmt.Errorf("render: %w", err))
		}

		// Make sure to write any build stats to disk first so it's available
		// to the post processors.
		if err := h.writeBuildStats(); err != nil {
			return err
		}

		// We need to do this before render deferred.
		if err := h.printPathWarningsOnce(); err != nil {
			h.SendError(fmt.Errorf("printPathWarnings: %w", err))
		}

		if err := h.renderDeferred(infol); err != nil {
			h.SendError(fmt.Errorf("renderDeferred: %w", err))
		}

		// This needs to be done after the deferred rendering to get complete template usage coverage.
		if err := h.printUnusedTemplatesOnce(); err != nil {
			h.SendError(fmt.Errorf("printPathWarnings: %w", err))
		}

		if err := h.postProcess(infol); err != nil {
			h.SendError(fmt.Errorf("postProcess: %w", err))
		}
	}

	if h.Metrics != nil {
		var b bytes.Buffer
		h.Metrics.WriteMetrics(&b)

		h.Log.Printf("\nTemplate Metrics:\n\n")
		h.Log.Println(b.String())

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Unwrap %w — it usually points to the deferred hook/shortcode template and line.
2. Fix the render hook / shortcode partial that errors during deferred rendering.
3. Verify resources referenced in deferred content exist (images, snippets).
4. Reproduce on a page using RenderShortcodes to isolate the failing template.

Example fix

<!-- before: render hook with bad call -->
{{ .Page.RenderString .Text | foo }}
<!-- foo undefined -> renderDeferred error -->

<!-- after -->
{{ .Page.RenderString .Text }}

// Validate render-hook partials and shortcodes resolve before relying on deferred render.
for _, p := range deferredPartialNames { if _, err := layouts.Lookup(p); err != nil { return err } }

if err := h.renderDeferred(l); err != nil {
    // deferred render errors cite the hook/shortcode; log and continue if non-critical
    h.Log.Errorf("renderDeferred: %v", err)
}

When it happens

Trigger: Raised at hugo_sites_build.go:213 when h.renderDeferred(infol) errors — a deferred template/hook fails to execute, or output writing for deferred content fails.

Common situations: A {{% shortcode %}} deferred render whose template errors; markdown render hooks referencing missing partials; an image/resource processed during deferred render that is missing or corrupt; version mismatch introducing a render-hook bug.

Related errors

• render: %w
• printPathWarnings: %w
• no compatible template found for shortcode %q in %s
• resources.PostProcess cannot be used in a deferred template
• error copying static files: %w

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