gohugoio/hugo · error

initRebuild: %w

Error message

initRebuild: %w

What it means

Wraps a failure of initRebuild() during a rebuild triggered by file events or remote changes. initRebuild resets build state for all sites; failure here means the rebuild preconditions are wrong (e.g. not in watch mode).

Source

Thrown at hugolib/hugo_sites_build.go:158

	conf := &config
	if conf.WhatChanged == nil {
		// Assume everything has changed
		conf.WhatChanged = &WhatChanged{needsPagesAssembly: true}
	}

	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
			})

View on GitHub (pinned to 52c9bd7908)

Solutions

1. If you invoke rebuilds programmatically, ensure Configs.Base.Internal.Watch is true (start a watcher first).
2. For one-off builds, don't pass WhatChanged — use a full build path instead.
3. When using `hugo server`, confirm it started successfully before file events arrive.
4. Update Hugo to a version matching your integration's rebuild API expectations.

Example fix

// before: rebuild without watch enabled
h.Build(&BuildCfg{WhatChanged: &WhatChanged{needsPagesAssembly: true}})
// -> initRebuild: rebuild called when not in watch mode

// after: enable watch before rebuild
cfg.Base.Internal.Watch = true
h.Build(&BuildCfg{WhatChanged: &WhatChanged{needsPagesAssembly: true}})

// Only request a rebuild when watch is enabled.
if !h.Configs.Base.Internal.Watch { return errors.New("enable watch before rebuild") }

if err := h.initRebuild(conf); err != nil {
    if strings.Contains(err.Error(), "not in watch mode") {
        // fall back to a full build
        return h.initSites()
    }
    return fmt.Errorf("initRebuild: %w", err)
}

When it happens

Trigger: Raised at hugo_sites_build.go:158 when h.initRebuild(conf) errors — most commonly 'rebuild called when not in watch mode' (hugo_sites_build.go:263) if a rebuild path is invoked without Internal.Watch set.

Common situations: A single-page/partial-rebuild API path called when the site was not initialized for watching; a custom integration invoking Build with WhatChanged.Changes() populated but watch disabled; misconfigured hugo server lifecycle.

Related errors

• error copying static files: %w
• error building site: %w
• failed to acquire a build lock: %w
• initSites: %w
• process: %w

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