gohugoio/hugo · error

failed to decode sitemap config in front matter

Error message

failed to decode sitemap config in front matter: %s

What it means

From the `sitemap` front-matter case (page__meta.go:770). config.DecodeSitemap merges the page's sitemap front-matter into the site default; if the value cannot be decoded (wrong types for changeFreq/priority/filename, or not a map), it errors and Hugo wraps it.

Solutions

1. Make `sitemap` a map with valid fields: changeFreq (string), priority (float 0–1), filename (string).
2. Use numeric literals for priority: `priority: 0.7`, not `priority: "0.7"` or words.
3. Drop the sitemap key if you only want site defaults.

Example fix

// before
---
sitemap: true
priority: high
---

// after
---
sitemap:
  changefreq: monthly
  priority: 0.7
  filename: sitemap.xml
---

{{/* sitemap front matter must be a map with typed fields */}}
{{/* changeFreq: string, priority: float 0-1, filename: string */}}

When it happens

Trigger: Front matter sets `sitemap:` to a scalar or gives known fields wrong types — e.g. `priority: high` (must be float), `changefreq: 5` (must be string), or `sitemap: true`. DecodeSitemap then fails.

Common situations: Copying sitemap examples with wrong types; YAML producing a string where a number is expected; treating sitemap as a boolean toggle.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to decode build config in front matter
• front matter field must be a map
• failed to decode media types
• no taxonomy configuration found for
• alias "" is an empty string

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/75ece28e99cd12b6. Report an issue: GitHub.

Appendix: 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 52c9bd7908)