gohugoio/hugo · error

key not allowed in cascade config

Error message

key %q not allowed in cascade config

What it means

Returned by DecodeCascadeConfig when a cascade entry map contains a key in the disallowedCascadeKeys set: 'kind', 'path', 'lang', or 'cascade'. These keys define the page tree structure or cascade recursion and cannot be set from within a cascade block. The check iterates every key in each cascade map after cleaning.

Solutions

1. Remove the disallowed key ('kind', 'path', 'lang', or 'cascade') from the cascade entry — the error message names the offending key.
2. If you meant to match by kind, put it under the target: { _target: { kind: 'page' }, params: {...} } (or target in newer Hugo versions).
3. If you meant to set language, use target.sites.matrix.languages instead of a top-level lang key.

Example fix

# before (front matter or config)
cascade:
  - kind: "page"
    params:
      banner: "hero.jpg"

# after — use _target for matching
cascade:
  - _target:
      kind: "page"
    params:
      banner: "hero.jpg"

// Validate cascade keys before decoding (Go-side)
var disallowedCascadeKeys = map[string]bool{
    "kind": true, "path": true, "lang": true, "cascade": true,
}
func validateCascadeKeys(cascadeMaps []map[string]any) error {
    for _, m := range cascadeMaps {
        for k := range m {
            if disallowedCascadeKeys[k] {
                return fmt.Errorf("key %q not allowed in cascade config", k)
            }
        }
    }
    return nil
}

When it happens

Trigger: Adding 'kind', 'path', 'lang', or 'cascade' as a top-level key inside a cascade entry in front matter or site config. For example: cascade: [{ kind: 'page', params: {...} }] — the 'kind' key is disallowed because cascade targets use _target.kind for matching, not a top-level kind.

Common situations: Confusing the cascade target's _target.kind matcher with a top-level kind field; trying to cascade the cascade itself (recursive); migrating from an older Hugo config format that allowed these keys; misunderstanding the cascade YAML/TOML structure.

Related errors

• did not match a valid Page Kind
• failed to compile cascade target
• failed to convert metadata for file
• failed to decode page map
• failed to decode sites from front matter

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

Appendix: source

Thrown at resources/page/page_matcher.go:161

		if err != nil {
			return CascadeConfig{}, nil, err
		}

		var cfgs []PageMatcherParamsConfig

		for _, m := range ms {
			m = hmaps.CleanConfigStringMap(m)
			var (
				c   PageMatcherParamsConfig
				err error
			)
			c, err = dec.mapToPageMatcherParamsConfig(m)
			if err != nil {
				return CascadeConfig{}, nil, err
			}
			for k := range m {
				if disallowedCascadeKeys[k] {
					return CascadeConfig{}, nil, fmt.Errorf("key %q not allowed in cascade config", k)
				}
			}
			cfgs = append(cfgs, c)
		}

		if len(cfgs) == 0 {
			return CascadeConfig{}, nil, nil
		}

		var n int
		for _, cfg := range cfgs {
			if len(cfg.Params) > 0 || len(cfg.Fields) > 0 {
				cfgs[n] = cfg
				n++
			}
		}

		if n == 0 {

View on GitHub (pinned to 52c9bd7908)