gohugoio/hugo · warning

printPathWarnings: %w

Error message

printPathWarnings: %w

What it means

Sent via SendError when printPathWarningsOnce() fails — the step that prints warnings about duplicate/overlapping output paths. The %w is the underlying error from the path-warning check.

Source

Thrown at hugolib/hugo_sites_build.go:209

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

	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

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Unwrap %w to see which path/stat operation failed.
2. Resolve duplicate output paths (same advice as assemble collision errors).
3. Ensure the publish directory is accessible for stat checks.
4. If non-blocking, run with path warnings disabled in config to confirm it's the source.

Example fix

// before: two outputs to /foo/index.html
[permalinks]
posts = "/foo/:slug"
pages = "/foo/:slug"

// after: distinct paths
[permalinks]
posts = "/posts/:slug"
pages = "/pages/:slug"

// Resolve all output paths and assert uniqueness up front.
if dups := duplicatePaths(pages); len(dups) > 0 { return fmt.Errorf("path overlaps: %v", dups) }

if err := h.printPathWarningsOnce(); err != nil {
    // path-warning failures are non-fatal diagnostics; log and continue
    h.Log.Warnf("printPathWarnings: %v", err)
}

When it happens

Trigger: Raised at hugo_sites_build.go:209 when h.printPathWarningsOnce() errors while detecting and reporting path collisions in the rendered output.

Common situations: Multiple pages/sections resolving to the same publish path causing the warning routine itself to fail; filesystem stat failures on the publish dir while computing overlaps; large sites where the path-map walk encounters an internal error.

Related errors

• assemble: %w
• render: %w
• renderDeferred: %w
• no compatible template found for shortcode %q in %s
• resources.PostProcess cannot be used in a deferred template

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