gohugoio/hugo · error

failed to render pages

Error message

%v failed to render pages: %w

What it means

The concurrent page-rendering pipeline (renderPages, which spawns workers via pageRenderer) received an error from one of the workers and propagated it through an error-collation channel. The message prefixes the resolved dimension names (language/version/role from s.resolveDimensionNames()) and wraps the per-page rendering error with %w. It signals that at least one page failed to render for the given site slice.

Solutions

1. Unwrap the %w error to find which specific page and template call failed.
2. Reproduce for just that dimension by filtering the build (e.g. hugo --renderSegments or environment-specific config) to iterate faster.
3. Fix the underlying layout/shortcode error (this error is an aggregator; the real fix is in the wrapped cause).
4. Re-run hugo to confirm the full build completes across all dimensions.

Example fix

// before: error reported as
// [en] [v1.2.0] failed to render pages: execute of template failed: ...

// after: fix the named layout referenced in the wrapped error, then rebuild

// Build errors surface via hugo's exit code; unwrap in logs to find the page.
if err := h.Build(config.BuildCfg{}); err != nil {
    var re *hugoRenderingError
    if errors.As(err, &re) {
        log.Printf("dimension %v failed: underlying=%v", re.Dimension, errors.Unwrap(err))
    }
    return err
}

When it happens

Trigger: Any per-page render error (template failure at site_render.go:71-120) sent on the results channel and surfaced via errs at line 116-118. The root cause is typically a layout/template error for a specific page under that language/version/role combination.

Common situations: A multilingual or multi-version site where one variant's layout is broken (missing partial, nil method) while others render fine; a page resource only present in some languages causing transform errors; output format mismatch in one dimension.

Related errors

• failed to acquire a build lock
• failed to compile cascade target
• failed to compile permalink target
• failed to decode sites from front matter
• failed to init mount

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

Appendix: source

Thrown at hugolib/site_render.go:118

				}
			}
			return radix.WalkContinue, nil
		},
	}

	if err := w.Walk(context.Background()); err != nil {
		return err
	}

	close(pages)

	wg.Wait()

	close(results)

	err := <-errs
	if err != nil {
		return fmt.Errorf("%v failed to render pages: %w", s.resolveDimensionNames(), err)
	}
	return nil
}

func pageRenderer(
	ctx *siteRenderContext,
	s *Site,
	pages <-chan *pageState,
	results chan<- error,
	wg *sync.WaitGroup,
) {
	defer wg.Done()

	sendErr := func(err error) bool {
		select {
		case results <- err:
			return true
		case <-s.h.Done():

View on GitHub (pinned to 52c9bd7908)