{"id":"526705e46c86c5d1","repo":"gohugoio/hugo","slug":"failed-to-decode-sites-from-front-matter-w","errorCode":null,"errorMessage":"failed to decode sites from front matter: %w","messagePattern":"failed to decode sites from front matter: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"resources/page/pagemeta/page_frontmatter.go","lineNumber":116,"sourceCode":"\t\tif err := pcfg.setFromFrontMatter(frontmatter); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\treturn pcfg.resolveContentType(ext, conf.GetConfigSection(\"mediaTypes\").(media.Types))\n}\n\nfunc (pcfg *PageConfigEarly) setFromFrontMatter(frontmatter map[string]any) error {\n\t// Needed for case insensitive fetching of params values.\n\thmaps.PrepareParams(frontmatter)\n\tpcfg.Frontmatter = frontmatter\n\n\tif v, found := frontmatter[pageMetaKeyMarkup]; found {\n\t\tpcfg.Content.Markup = cast.ToString(v)\n\t}\n\n\tif v, found := frontmatter[pageMetaKeySites]; found {\n\t\tif err := mapstructure.WeakDecode(v, &pcfg.Sites); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to decode sites from front matter: %w\", err)\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc (p *PageConfigEarly) setCascadeEarlyValueIfNotSet(key string, value any) (done bool) {\n\tswitch key {\n\tcase pageMetaKeySites:\n\t\tp.Sites.SetFromParamsIfNotSet(value.(hmaps.Params))\n\t}\n\n\treturn !p.Sites.Matrix.IsZero()\n}\n\n// Page config that needs to be set early.\ntype PageConfigEarly struct {\n\tKind            string // The kind of page, e.g. \"page\", \"section\", \"home\" etc. This is usually derived from the content path.\n\tPath            string // The canonical path to the page, e.g. /sect/mypage. Note: Leading slash, no trailing slash, no extensions or language identifiers.","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/resources/page/pagemeta/page_frontmatter.go#L98-L134","documentation":"When reading a page's front matter, Hugo weak-decodes the `sites` key into the page's sites-matrix configuration (the multi-site/multilingual matrix introduced with the sites config). This error means the value under `sites` has a shape mapstructure cannot coerce into the expected Sites struct — wrong type, wrong nesting, or invalid field values.","triggerScenarios":"A content file whose front matter contains a `sites` key with an incompatible structure — e.g. a scalar or list where a map is expected, or nested fields that don't match the Sites schema — causing mapstructure.WeakDecode to fail during PageConfigEarly.setFromFrontMatter.","commonSituations":"Hand-written YAML/TOML front matter with wrong indentation making `sites` a string or list; sites config copied from site-level hugo.toml in an incompatible shape; a pre-existing custom `sites` param colliding with the newer reserved key after upgrading Hugo.","solutions":["Fix the `sites` front matter value to match the documented sites-matrix shape (a map/object, not a scalar or list).","If `sites` was a custom parameter, move it under `params.sites` so it no longer collides with the reserved key.","Check YAML indentation/TOML table syntax in the offending file — the wrapped decode error names the mismatched field."],"exampleFix":"# before (front matter)\nsites: \"en,de\"\n# after\nparams:\n  sites: \"en,de\"   # or use the proper sites matrix map shape","handlingStrategy":"validation","validationCode":"# front matter: `sites` must be a list of strings\n---\nsites: [\"en\", \"fr\"]\n---","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the `sites` front matter key a plain string array, not a map or scalar","Validate front matter with `hugo --printPathWarnings` / a lint pass in CI","When templating front matter via archetypes, quote values to avoid YAML type surprises"],"tags":["front-matter","decoding","multilingual","hugo"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}