gohugoio/hugo · error

failed to decode sitemap config in front matter: %s

Error message

failed to decode sitemap config in front matter: %s

What it means

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.

Source

Thrown at hugolib/page__meta.go:770

		case "layout":
			pcfg.Layout = cast.ToString(v)
			pcfg.Params[loki] = pcfg.Layout
		case "weight":
			pcfg.Weight = cast.ToInt(v)
			pcfg.Params[loki] = pcfg.Weight
		case "aliases":
			pcfg.Aliases = cast.ToStringSlice(v)
			for i, alias := range pcfg.Aliases {
				if strings.HasPrefix(alias, "http://") || strings.HasPrefix(alias, "https://") {
					return fmt.Errorf("http* aliases not supported: %q", alias)
				}
				pcfg.Aliases[i] = filepath.ToSlash(alias)
			}
			pcfg.Params[loki] = pcfg.Aliases
		case "sitemap":
			pcfg.Sitemap, err = config.DecodeSitemap(ps.s.conf.Sitemap, hmaps.ToStringMap(v))
			if err != nil {
				return fmt.Errorf("failed to decode sitemap config in front matter: %s", err)
			}
			sitemapSet = true
		case "iscjklanguage":
			isCJKLanguage = new(bool)
			*isCJKLanguage = cast.ToBool(v)
		case "translationkey":
			pcfg.TranslationKey = cast.ToString(v)
			pcfg.Params[loki] = pcfg.TranslationKey
		case "resources":
			var resources []map[string]any
			handled := true

			switch vv := v.(type) {
			case []map[any]any:
				for _, vvv := range vv {
					resources = append(resources, hmaps.ToStringMap(vvv))
				}
			case []map[string]any:

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Use the supported map shape: `sitemap:\n changefreq: monthly\n priority: 0.8\n disable: false`.
2. Ensure priority is numeric (0.0–1.0) and disable is a boolean.
3. Remove the sitemap key if you only need the site defaults from your site config.

Example fix

# before
---
sitemap: weekly
---
# after
---
sitemap:
  changefreq: weekly
  priority: 0.5
---

// Validate sitemap front matter shape
if s, ok := fm["sitemap"]; ok {
    m, ok := s.(map[string]any)
    if !ok {
        return fmt.Errorf("sitemap must be a map")
    }
    if p, ok := m["priority"]; ok {
        if _, err := cast.ToFloat64E(p); err != nil {
            return fmt.Errorf("sitemap.priority must be numeric: %v", err)
        }
    }
}

func isSitemapConfig(v any) bool {
    _, ok := v.(map[string]any)
    return ok
}

if err := site.Build(); err != nil {
    if strings.Contains(err.Error(), "failed to decode sitemap config") {
        // fix the page's sitemap block: changefreq (string), priority (number), filename
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• media type %q not found
• key %q not allowed in cascade config
• failed to decode build config in front matter: %s%s
• unable to cast %#v of type %T to []map[string]interface{}
• language %q not found

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/75ece28e99cd12b6.json. Report an issue: GitHub ↗.