gohugoio/hugo · error

assemble: %w

Error message

assemble: %w

What it means

Wraps a failure of the assemble() step — where processed pages are assembled into the page trees, relations resolved, and taxonomies built. The %w is the assembly-phase error.

Source

Thrown at hugolib/hugo_sites_build.go:178

				} 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) {
				return terminal.ProgressNormal, 0.20
			})

			return nil
		}

		if prepareErr = prepare(); prepareErr != nil {
			h.SendError(prepareErr)
		}
	}

	for s := range h.allSites(nil) {
		s.state = siteStateReady
	}

	if prepareErr == nil {

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Unwrap %w — often names the conflicting page path or relation.
2. Resolve duplicate output paths by renaming pages or adjusting permalink config.
3. Check translations point to valid counterpart pages.
4. Simplify to a minimal content set and re-add to isolate the conflict.

Example fix

# before: two pages share a path
content/a/index.md   -> /a/
content/a.md         -> /a/   # collision

# after: keep one canonical source
rm content/a.md

// Detect duplicate output paths before building by simulating permalink resolution.
seen := map[string]string{}
for _, p := range pages {
    out := permalinkFor(p)
    if prev, dup := seen[out]; dup { return fmt.Errorf("path clash %s vs %s", prev, p.File) }
    seen[out] = p.File
}

if err := h.assemble(ctx, l, conf); err != nil {
    // assemble errors usually cite a clashing path; log and surface for fixing
    h.Log.Errorf("assemble: %v", err)
    return err
}

When it happens

Trigger: Raised at hugo_sites_build.go:178 when h.assemble(ctx, infol, conf) errors during page-tree assembly — duplicate paths, relation resolution failures, or rendering-dependent state errors.

Common situations: Two pages resolving to the same output path (duplicate permalinks/URLs); circular or broken page references; a permalink pattern that produces invalid paths; multilingual alignment issues.

Related errors

• process: %w
• printPathWarnings: %w
• %q must resolve to an absolute directory
• %q is a root folder and not allowed as cache dir
• failed to resolve output path %q: %w

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