gohugoio/hugo · error

error building site: %w

Error message

error building site: %w

What it means

Wrapper added in fullBuild around buildSites, i.e. the main HugoSites.Build render pass. Any content, template, taxonomy, or output-format error surfaces through this wrapper, marking that the failure happened during site rendering as opposed to static-file copying.

Source

Thrown at commands/hugobuilder.go:584

	c.r.logger.Println(hugo.BuildVersionString())
	c.r.logger.Println()
	if terminal.IsTerminal(os.Stdout) {
		defer func() {
			fmt.Print(showCursor + clearLine)
		}()
	}

	copyStaticFunc := func() error {
		cnt, err := c.copyStatic()
		if err != nil {
			return fmt.Errorf("error copying static files: %w", err)
		}
		langCount = cnt
		return nil
	}
	buildSitesFunc := func() error {
		if err := c.buildSites(noBuildLock); err != nil {
			return fmt.Errorf("error building site: %w", err)
		}
		return nil
	}
	// Do not copy static files and build sites in parallel if cleanDestinationDir is enabled.
	// This flag deletes all static resources in /public folder that are missing in /static,
	// and it does so at the end of copyStatic() call.
	var cleanDestinationDir bool
	c.withConf(func(conf *commonConfig) {
		cleanDestinationDir = conf.configs.Base.CleanDestinationDir
	})
	if cleanDestinationDir {
		if err := copyStaticFunc(); err != nil {
			return err
		}
		if err := buildSitesFunc(); err != nil {
			return err
		}
	} else {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Read the wrapped error chain — it usually includes file:line:col of the failing template or content file; fix that file.
2. Run with --logLevel debug (or -v) for more context.
3. If it appeared after a Hugo upgrade, check the release notes for removed/deprecated template features.
4. If the error mentions SCSS/Sass, install the extended edition or dart-sass.

// run a config/content sanity pass first: hugo --renderToMemory or
// hugo config to catch config errors before a full build

// Hugo build errors wrap file-error details; unwrap for position info
var fe herrors.FileError
if errors.As(err, &fe) {
    // fe has filename/line/col of the failing template or content file
}

if err := b.build(); err != nil {
    if strings.Contains(err.Error(), "error building site") {
        // surface the wrapped cause (template error, content parse error) to the user
        log.Printf("build failed: %v", err)
    }
    return err
}

When it happens

Trigger: buildSites returning an error during a full `hugo` build: template execution errors, invalid front matter, failing shortcodes, resource/asset pipeline errors (e.g. missing SCSS transpiler), or errors raised via the errorf/erroridf template funcs.

Common situations: Template errors after upgrading Hugo versions (deprecated constructs removed), missing extended edition for SCSS, malformed front matter dates, or content referencing missing resources.

Related errors

• failed to transform template %q: %w
• failed to create page from pageMetaSource %s: %w
• failed to create term page %q: %w
• failed to create page from file %q: %w
• failed to create page meta from file %q: %w

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/bd4fe4d383e3bf5c.json. Report an issue: GitHub ↗.