gohugoio/hugo · error

error building site

Error message

error building site: %w

What it means

`fullBuild` runs `c.buildSites(noBuildLock)` concurrently with static copying. This wraps the core Hugo build failure, which is the catch-all for template, content, page parsing, and rendering errors produced during `hugolib.HugoSites.Build`. The wrapped error usually carries Hugo's file-error context (line/column).

Solutions

1. Read the wrapped error for the file path and line/column (Hugo annotates file errors).
2. Run `hugo --verbose` or check the printed file-error context to pinpoint the failing template/content.
3. Comment out recently changed templates/pages to bisect the source.
4. Verify the theme is compatible with the installed Hugo version (`hugo version`).

Example fix

// before
{{ range .Pages }}
  <li>{{ .Title }}</li>
<!-- missing {{ end }} -->
// after
{{ range .Pages }}
  <li>{{ .Title }}</li>
{{ end }}

// Use hugo in check/dry-run mode to catch template/content errors early.
// $ hugo --renderToMemory --quiet  (non-zero exit signals a build issue)

null

// hugolib.FileError carries file:line:col context; narrow on it.
var fe *herrors.FileError
if errors.As(err, &fe) {
  log.Printf("build error at %s:%d:%d: %s", fe.Position().Filename, fe.Position().Line, fe.Position().Column, fe.Error())
}

When it happens

Trigger: Triggered when `buildSites` returns non-nil — syntax errors in templates, invalid shortcodes, unparseable Markdown, type errors in front matter, missing layouts referenced by pages, or unsupported content features.

Common situations: A typo in a Go template (`{{ range .Pages }}` unclosed), an undefined partial or shortcode, invalid TOML/YAML front matter, an incompatible theme after a Hugo version upgrade, or a content file with an unsupported output format.

Related errors

• process
• render
• assemble
• can't apply the operator to the values
• content source: failed to convert %T to string

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

Appendix: 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 52c9bd7908)