{"record":{"id":"a0f1079e32abd1e3","repo":"gohugoio/hugo","slug":"failed-to-decode-build-config-in-front-matter-s","errorCode":null,"errorMessage":"failed to decode build config in front matter: %s%s","messagePattern":"failed to decode build config in front matter: (.+?)(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/page__meta.go","lineNumber":671,"sourceCode":"\t} else {\n\t\tbuildConfig = pcfg.Params[\"build\"]\n\t\tisNewBuildKeyword = true\n\t}\n\tpm.pageConfig.Build, err = pagemeta.DecodeBuildConfig(buildConfig)\n\tif err != nil {\n\t\tvar msgDetail string\n\t\tif isNewBuildKeyword {\n\t\t\tmsgDetail = `. We renamed the _build keyword to build in Hugo 0.123.0. We recommend putting user defined params in the params section, e.g.:\n---\ntitle: \"My Title\"\nparams:\n  build: \"My Build\"\n---\n´\n\n`\n\t\t}\n\t\treturn fmt.Errorf(\"failed to decode build config in front matter: %s%s\", err, msgDetail)\n\t}\n\n\tvar draft, published, isCJKLanguage *bool\n\tvar userParams map[string]any\n\tfor k, v := range pcfg.Params {\n\t\tloki := strings.ToLower(k)\n\n\t\tif loki == \"params\" {\n\t\t\tvv, err := hmaps.ToParamsAndPrepare(v)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"front matter field %q must be a map: %w\", k, err)\n\t\t\t}\n\t\t\tuserParams = vv\n\t\t\tdelete(pcfg.Params, k)\n\t\t\tcontinue\n\t\t}\n\n\t\tif loki == \"published\" { // Intentionally undocumented","sourceCodeStart":653,"sourceCodeEnd":689,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/hugolib/page__meta.go#L653-L689","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Make `build` a map with valid keys, e.g. `build: { list: never, render: never }`.","If `build` was a user param, move it under `params:` to avoid the reserved-key collision.","Migrate legacy `_build` to `build` (Hugo 0.123.0+)."],"exampleFix":"// before\n---\ntitle: \"About\"\nbuild: true\n---\n\n// after\n---\ntitle: \"About\"\nbuild:\n  list: never\n  render: never\n---","handlingStrategy":"validation","validationCode":"{{/* front matter: keep build a map with valid keys */}}\n{{/* valid: build: { list: never|always|listlocally, render: never|always|link } */}}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep `build` front matter a map with list/render enums.","Don't reuse the reserved `build` key for user params — put them under params.","Migrate legacy `_build` to `build`."],"tags":["front-matter","build-config","config","decode"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}