gohugoio/hugo · error

initSites: %w

Error message

initSites: %w

What it means

Wraps a failure of initSites() during a full (non-rebuild) build. initSites() calls h.reset() to clear build state; the wrapper surfaces any error from that reset/init step.

Source

Thrown at hugolib/hugo_sites_build.go:162

	}

	var prepareErr error

	if !config.PartialReRender {
		prepare := func() error {
			init := func(conf *BuildCfg) error {
				for _, s := range h.Sites {
					s.Deps.BuildStartListeners.Notify()
				}

				if len(events) > 0 || len(conf.WhatChanged.Changes()) > 0 {
					// Rebuild
					if err := h.initRebuild(conf); err != nil {
						return fmt.Errorf("initRebuild: %w", err)
					}
				} else {
					if err := h.initSites(); err != nil {
						return fmt.Errorf("initSites: %w", err)
					}
				}

				return nil
			}

			ctx := context.Background()

			if err := h.process(ctx, infol, conf, init, events...); err != nil {
				return fmt.Errorf("process: %w", err)
			}
			h.reportProgress(func() (state terminal.ProgressState, progress float64) {
				return terminal.ProgressNormal, 0.15
			})
			if err := h.assemble(ctx, infol, conf); err != nil {
				return fmt.Errorf("assemble: %w", err)
			}
			h.reportProgress(func() (state terminal.ProgressState, progress float64) {

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Unwrap the %w to find the concrete reset/init failure.
2. Avoid sharing/mutating a HugoSites instance across goroutines during Build.
3. Re-create the HugoSites (hugo.NewHugoSites) fresh instead of reusing a tainted instance.
4. Reproduce with a minimal config and bisect templates/modules if internal state is suspected.

Example fix

// before: reuse tainted sites across builds
hs.Build(cfg1)
// later...
hs.Build(cfg2)  // initSites fails on dirty state

// after: rebuild sites fresh
hs, _ = hugo.NewHugoSites(d1)
hs.Build(cfg2)

// Reuse a HugoSites instance only between successful builds; rebuild fresh after a failure.
if lastBuildFailed { hs, _ = hugo.NewHugoSites(deps) }

if err := h.initSites(); err != nil {
    // recreate sites rather than reuse a half-reset instance
    h, _ = hugo.NewHugoSites(h.Deps)
    return fmt.Errorf("initSites: %w", err)
}

When it happens

Trigger: Raised at hugo_sites_build.go:162 when h.initSites() returns an error during the initial build path (no file events / no WhatChanged). Typically rare since initSites mainly resets state.

Common situations: Custom Hugo integration where reset() encounters inconsistent state; a Hugo internal panic-like condition during site teardown; concurrent mutation of HugoSites during init in an embedded host.

Related errors

• failled to create base cache directory: %s
• error copying static files: %w
• error building site: %w
• build filesystems: %w
• create main fs: %w

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