{"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":"validation","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/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/page__meta.go#L653-L689","documentation":"Hugo failed to decode the `build` (or legacy `_build`) front matter key into its pagemeta.BuildConfig struct (fields like render, list, publishResources). Since Hugo 0.123.0 `build` is a reserved front matter keyword, so any value that isn't a valid build-options map fails decoding. The extra message detail is appended only for the new `build` keyword to warn users who used `build` as a personal param.","triggerScenarios":"A page's front matter contains `build:` (or deprecated `_build:`) with a value that pagemeta.DecodeBuildConfig cannot map — e.g. a string (`build: \"My Build\"`), a list, or a map with wrongly-typed fields such as `render: 5` instead of one of never/always/link.","commonSituations":"Most common after upgrading past Hugo 0.123.0: sites that used `build` as a user-defined param (e.g. a build number or CI tag) at the top level of front matter suddenly break, because `_build` was renamed to `build` and now collides. Also typos inside legitimate build option maps.","solutions":["If `build` was your own custom param, move it under the `params:` section of front matter (`params:\\n  build: ...`) and access it via .Params.build.","If you intend Hugo build options, make it a map with valid keys/values: `build:\\n  render: never\\n  list: local\\n  publishResources: false`.","Migrate any remaining `_build` keys to `build` (the old key is deprecated since 0.145.0)."],"exampleFix":"# before\n---\ntitle: \"My Title\"\nbuild: \"My Build\"\n---\n# after\n---\ntitle: \"My Title\"\nparams:\n  build: \"My Build\"\n---","handlingStrategy":"validation","validationCode":"// Validate front matter 'build' before creating the page\nif b, ok := fm[\"build\"]; ok {\n    if _, ok := b.(map[string]any); !ok {\n        return fmt.Errorf(\"build must be a map, got %T\", b)\n    }\n}","typeGuard":"func isMap(v any) bool {\n    _, ok := v.(map[string]any)\n    return ok\n}","tryCatchPattern":"if err := site.Build(); err != nil {\n    if strings.Contains(err.Error(), \"failed to decode build config\") {\n        // report offending page's front matter to the author\n    }\n    return err\n}","preventionTips":["Keep the front matter `build` key a map with only documented fields (render, list, publishResources)","Lint front matter with a YAML/TOML schema in CI before running hugo","Don't reuse the reserved key `build` for custom page params — put custom data under `params`"],"tags":["hugo","front-matter","build-config","config"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}