{"record":{"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":"exception","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/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/resources/page/pagemeta/page_frontmatter.go#L98-L134","documentation":"Thrown while decoding the optional 'sites' front matter key into the sitesmatrix.Sites struct via mapstructure.WeakDecode. The wrapped error is the underlying decode failure, so the front matter 'sites' block could not be coerced into the expected matrix/complements shape.","triggerScenarios":"A content file (or content-adapter map) sets a 'sites:' front matter key to a value whose structure does not match sitesmatrix.Sites, e.g. a bare string, a list of scalars, or a map with unrecognized fields.","commonSituations":"Authors misunderstand the multi-site/matrix feature and write 'sites: en' or 'sites: [en, fr]' instead of the matrix glob format. Also occurs after a Hugo upgrade that changed the 'sites' schema.","solutions":["Check the wrapped error message for the exact mapstructure field that failed.","Format the 'sites' front matter key per the sitesmatrix spec (matrix/complements glob maps).","Remove the 'sites' key entirely if you do not need multi-site routing; Hugo will fall back to the site default."],"exampleFix":"# before\n---\nsites: en\n---\n# after (or omit it)\n---\nsites:\n  matrix:\n    language: en\n---","handlingStrategy":"validation","validationCode":"if v, found := fm[\"sites\"]; found {\n    if err := mapstructure.WeakDecode(v, &target); err != nil {\n        return fmt.Errorf(\"bad sites front matter: %w\", err)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := pcfg.SetMetaPreFromMap(ext, fm, logger, conf); err != nil {\n    logger.Errorf(\"front matter sites invalid in %s: %v\", path, err)\n}","preventionTips":["Follow the sitesmatrix.Sites schema (matrix/complements glob maps) for the 'sites' key.","Omit 'sites' unless you need multi-site routing.","Validate front matter with a linter before committing."],"tags":["hugo","front-matter","multilingual","sites-matrix","configuration"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}