gohugoio/hugo · error

front matter field must be a map

Error message

front matter field %q must be a map: %w

What it means

From the front-matter params decoder (page__meta.go:682). The `params` front-matter key must decode to a map[string]any via hmaps.ToParamsAndPrepare; if it is a scalar, list, or otherwise not a map, that call errors and Hugo surfaces it with the offending key name.

Solutions

1. Make `params` a keyed map: `params:\n key: value` (YAML) or `[params]\nkey = "value"` (TOML).
2. Verify indentation so params parses as a map, not a scalar/list.
3. Move array values under named keys if you need collections inside params.

Example fix

// before
---
params: [foo, bar]
---

// after
---
params:
  tags:
    - foo
    - bar
---

# params front matter must be a map; check before commit
# YAML: ensure `params:` is followed by indented keys, never a scalar/list

When it happens

Trigger: Front matter writes `params:` as a scalar (`params: foo`) or a sequence (`params: [a, b]`) instead of a keyed map. The decoder rejects anything it cannot represent as params.

Common situations: Copying a snippet that uses an array under params; YAML indentation making params a string; TOML table misuse.

Related errors

• failed to decode build config in front matter
• failed to decode sitemap config in front matter
• failed to decode media types
• failed to marshal params
• no taxonomy configuration found for

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

Appendix: source

Thrown at hugolib/page__meta.go:682

params:
  build: "My Build"
---
´

`
		}
		return fmt.Errorf("failed to decode build config in front matter: %s%s", err, msgDetail)
	}

	var draft, published, isCJKLanguage *bool
	var userParams map[string]any
	for k, v := range pcfg.Params {
		loki := strings.ToLower(k)

		if loki == "params" {
			vv, err := hmaps.ToParamsAndPrepare(v)
			if err != nil {
				return fmt.Errorf("front matter field %q must be a map: %w", k, err)
			}
			userParams = vv
			delete(pcfg.Params, k)
			continue
		}

		if loki == "published" { // Intentionally undocumented
			vv, err := cast.ToBoolE(v)
			if err == nil {
				published = &vv
			}
			// published may also be a date
			continue
		}

		if ps.s.frontmatterHandler.IsDateKey(loki) {
			continue
		}

View on GitHub (pinned to 52c9bd7908)