gohugoio/hugo · error

failed to decode build config in front matter

Error message

failed to decode build config in front matter: %s%s

What it means

From the build-config front-matter decoder (page__meta.go:671). pagemeta.DecodeBuildConfig (resources/page/pagemeta/pagemeta.go:67) WeakDecodes the `build` (or legacy `_build`) front-matter value into BuildConfig; if the value isn't a map or its fields (list/render) have wrong types, decoding fails and Hugo wraps it, appending a guidance note when the new `build` keyword is in use (renamed from `_build` in 0.123.0).

Solutions

1. Make `build` a map with valid keys, e.g. `build: { list: never, render: never }`.
2. If `build` was a user param, move it under `params:` to avoid the reserved-key collision.
3. Migrate legacy `_build` to `build` (Hugo 0.123.0+).

Example fix

// before
---
title: "About"
build: true
---

// after
---
title: "About"
build:
  list: never
  render: never
---

{{/* front matter: keep build a map with valid keys */}}
{{/* valid: build: { list: never|always|listlocally, render: never|always|link } */}}

When it happens

Trigger: Front matter sets `build:` to a scalar/list instead of a map, or gives list/render a value that mapstructure cannot coerce into the expected string enum. With the new `build` keyword, the appended hint recommends moving user params into the params section.

Common situations: Naming a user param `build` at the top level (collides with the reserved key); writing `build: true` instead of `build: { render: never }`; leftover `_build` from very old themes.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to decode sitemap config in front matter
• front matter field must be a map
• failed to decode media types
• no taxonomy configuration found for
• alias "" is an empty string

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

Appendix: source

Thrown at hugolib/page__meta.go:671

	} else {
		buildConfig = pcfg.Params["build"]
		isNewBuildKeyword = true
	}
	pm.pageConfig.Build, err = pagemeta.DecodeBuildConfig(buildConfig)
	if err != nil {
		var msgDetail string
		if isNewBuildKeyword {
			msgDetail = `. We renamed the _build keyword to build in Hugo 0.123.0. We recommend putting user defined params in the params section, e.g.:
---
title: "My Title"
params:
  build: "My Build"
---
´

`
		}
		return fmt.Errorf("failed to decode build config in front matter: %s%s", err, msgDetail)
	}

	var draft, published, isCJKLanguage *bool
	var userParams map[string]any
	for k, v := range pcfg.Params {
		loki := strings.ToLower(k)

		if loki == "params" {
			vv, err := hmaps.ToParamsAndPrepare(v)
			if err != nil {
				return fmt.Errorf("front matter field %q must be a map: %w", k, err)
			}
			userParams = vv
			delete(pcfg.Params, k)
			continue
		}

		if loki == "published" { // Intentionally undocumented

View on GitHub (pinned to 52c9bd7908)