gohugoio/hugo · error

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

Error message

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

What it means

The reserved `params` front matter key must be a map of user-defined parameters. Hugo runs it through hmaps.ToParamsAndPrepare, which lower-cases keys and normalizes nested maps; if the value isn't map-shaped the conversion fails and the whole page build errors, because Hugo cannot merge arbitrary scalars into .Params.

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 8a468df065)

Solutions

1. Make `params` a map: `params:\n myKey: myValue` (YAML) or `[params]` table (TOML).
2. If you wanted a single custom value, nest it under params rather than replacing params itself.
3. Check YAML indentation — child keys must be indented under `params:`.

Example fix

# before
---
params: featured
---
# after
---
params:
  featured: true
---

// Check reserved map-typed fields (build, sitemap, outputs config, etc.)
for _, k := range []string{"build", "sitemap"} {
    if v, ok := fm[k]; ok {
        if _, ok := v.(map[string]any); !ok {
            return fmt.Errorf("front matter %q must be a map", k)
        }
    }
}

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

if err := h.Build(config); err != nil {
    var pe *herrors.ErrorWithFileContext
    if errors.As(err, &pe) {
        // pinpoint the file whose field has the wrong type
    }
    return err
}

When it happens

Trigger: Front matter contains `params:` with a non-map value — a string, number, or list (e.g. `params: foo` or `params:\n - a\n - b`). Any page processed by hugolib with such front matter triggers it during pageMeta setup.

Common situations: Users who previously used `params` as their own scalar field, YAML indentation mistakes that turn an intended map into a string or list, or TOML `params = "x"` instead of a `[params]` table.

Related errors

• failed to parse file %q: %s
• error processing file %q
• failed to convert metadata for file %q: %s
• max depth exceeded
• failed to unmarshal config for path %q: %w

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