{"record":{"id":"9b12ab4952788a09","repo":"gohugoio/hugo","slug":"key-q-not-allowed-in-cascade-config","errorCode":null,"errorMessage":"key %q not allowed in cascade config","messagePattern":"key %q not allowed in cascade config","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"resources/page/page_matcher.go","lineNumber":161,"sourceCode":"\t\tif err != nil {\n\t\t\treturn CascadeConfig{}, nil, err\n\t\t}\n\n\t\tvar cfgs []PageMatcherParamsConfig\n\n\t\tfor _, m := range ms {\n\t\t\tm = hmaps.CleanConfigStringMap(m)\n\t\t\tvar (\n\t\t\t\tc   PageMatcherParamsConfig\n\t\t\t\terr error\n\t\t\t)\n\t\t\tc, err = dec.mapToPageMatcherParamsConfig(m)\n\t\t\tif err != nil {\n\t\t\t\treturn CascadeConfig{}, nil, err\n\t\t\t}\n\t\t\tfor k := range m {\n\t\t\t\tif disallowedCascadeKeys[k] {\n\t\t\t\t\treturn CascadeConfig{}, nil, fmt.Errorf(\"key %q not allowed in cascade config\", k)\n\t\t\t\t}\n\t\t\t}\n\t\t\tcfgs = append(cfgs, c)\n\t\t}\n\n\t\tif len(cfgs) == 0 {\n\t\t\treturn CascadeConfig{}, nil, nil\n\t\t}\n\n\t\tvar n int\n\t\tfor _, cfg := range cfgs {\n\t\t\tif len(cfg.Params) > 0 || len(cfg.Fields) > 0 {\n\t\t\t\tcfgs[n] = cfg\n\t\t\t\tn++\n\t\t\t}\n\t\t}\n\n\t\tif n == 0 {","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/resources/page/page_matcher.go#L143-L179","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the disallowed key ('kind', 'path', 'lang', or 'cascade') from the cascade entry — the error message names the offending key.","If you meant to match by kind, put it under the target: { _target: { kind: 'page' }, params: {...} } (or target in newer Hugo versions).","If you meant to set language, use target.sites.matrix.languages instead of a top-level lang key."],"exampleFix":"# before (front matter or config)\ncascade:\n  - kind: \"page\"\n    params:\n      banner: \"hero.jpg\"\n\n# after — use _target for matching\ncascade:\n  - _target:\n      kind: \"page\"\n    params:\n      banner: \"hero.jpg\"","handlingStrategy":"validation","validationCode":"// Validate cascade keys before decoding (Go-side)\nvar disallowedCascadeKeys = map[string]bool{\n    \"kind\": true, \"path\": true, \"lang\": true, \"cascade\": true,\n}\nfunc validateCascadeKeys(cascadeMaps []map[string]any) error {\n    for _, m := range cascadeMaps {\n        for k := range m {\n            if disallowedCascadeKeys[k] {\n                return fmt.Errorf(\"key %q not allowed in cascade config\", k)\n            }\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never put 'kind', 'path', 'lang', or 'cascade' at the top level of a cascade entry — use _target for matching.","Use _target.kind, _target.path, and target.sites.matrix.languages instead of the disallowed top-level keys.","Validate cascade front matter with 'hugo --renderToMemory' before committing."],"tags":["hugo","cascade","front-matter","config-validation"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}