{"id":"75ece28e99cd12b6","repo":"gohugoio/hugo","slug":"failed-to-decode-sitemap-config-in-front-matter","errorCode":null,"errorMessage":"failed to decode sitemap config in front matter: %s","messagePattern":"failed to decode sitemap config in front matter: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/page__meta.go","lineNumber":770,"sourceCode":"\t\tcase \"layout\":\n\t\t\tpcfg.Layout = cast.ToString(v)\n\t\t\tpcfg.Params[loki] = pcfg.Layout\n\t\tcase \"weight\":\n\t\t\tpcfg.Weight = cast.ToInt(v)\n\t\t\tpcfg.Params[loki] = pcfg.Weight\n\t\tcase \"aliases\":\n\t\t\tpcfg.Aliases = cast.ToStringSlice(v)\n\t\t\tfor i, alias := range pcfg.Aliases {\n\t\t\t\tif strings.HasPrefix(alias, \"http://\") || strings.HasPrefix(alias, \"https://\") {\n\t\t\t\t\treturn fmt.Errorf(\"http* aliases not supported: %q\", alias)\n\t\t\t\t}\n\t\t\t\tpcfg.Aliases[i] = filepath.ToSlash(alias)\n\t\t\t}\n\t\t\tpcfg.Params[loki] = pcfg.Aliases\n\t\tcase \"sitemap\":\n\t\t\tpcfg.Sitemap, err = config.DecodeSitemap(ps.s.conf.Sitemap, hmaps.ToStringMap(v))\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to decode sitemap config in front matter: %s\", err)\n\t\t\t}\n\t\t\tsitemapSet = true\n\t\tcase \"iscjklanguage\":\n\t\t\tisCJKLanguage = new(bool)\n\t\t\t*isCJKLanguage = cast.ToBool(v)\n\t\tcase \"translationkey\":\n\t\t\tpcfg.TranslationKey = cast.ToString(v)\n\t\t\tpcfg.Params[loki] = pcfg.TranslationKey\n\t\tcase \"resources\":\n\t\t\tvar resources []map[string]any\n\t\t\thandled := true\n\n\t\t\tswitch vv := v.(type) {\n\t\t\tcase []map[any]any:\n\t\t\t\tfor _, vvv := range vv {\n\t\t\t\t\tresources = append(resources, hmaps.ToStringMap(vvv))\n\t\t\t\t}\n\t\t\tcase []map[string]any:","sourceCodeStart":752,"sourceCodeEnd":788,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/page__meta.go#L752-L788","documentation":"The `sitemap` front matter key lets a page override site-level sitemap settings (changefreq, priority, disable, filename). Hugo merges it over the site config via config.DecodeSitemap; if the map's values fail to decode (wrong types or non-map shape after ToStringMap), page processing errors out.","triggerScenarios":"Front matter contains `sitemap:` with values that don't decode — e.g. `priority: \"high\"` instead of a number in [0,1], `disable: \"yes\"` with an uncastable type, or a scalar instead of a map.","commonSituations":"Users setting priority as a word instead of a float, copying sitemap XML terminology directly into front matter, or YAML type surprises (quoted numbers usually work, but structs/lists don't).","solutions":["Use the supported map shape: `sitemap:\\n  changefreq: monthly\\n  priority: 0.8\\n  disable: false`.","Ensure priority is numeric (0.0–1.0) and disable is a boolean.","Remove the sitemap key if you only need the site defaults from your site config."],"exampleFix":"# before\n---\nsitemap: weekly\n---\n# after\n---\nsitemap:\n  changefreq: weekly\n  priority: 0.5\n---","handlingStrategy":"validation","validationCode":"// Validate sitemap front matter shape\nif s, ok := fm[\"sitemap\"]; ok {\n    m, ok := s.(map[string]any)\n    if !ok {\n        return fmt.Errorf(\"sitemap must be a map\")\n    }\n    if p, ok := m[\"priority\"]; ok {\n        if _, err := cast.ToFloat64E(p); err != nil {\n            return fmt.Errorf(\"sitemap.priority must be numeric: %v\", err)\n        }\n    }\n}","typeGuard":"func isSitemapConfig(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 sitemap config\") {\n        // fix the page's sitemap block: changefreq (string), priority (number), filename\n    }\n    return err\n}","preventionTips":["Only use the documented sitemap keys: changefreq, priority, filename, disable","Keep priority numeric (0.0–1.0) — don't quote it into an unparseable string","Set site-wide sitemap defaults in config and override per page only when needed"],"tags":["hugo","front-matter","sitemap","config"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}