{"record":{"id":"1e622233bd14395c","repo":"gohugoio/hugo","slug":"permalinks-configuration-invalid-unknown-value-q-1e6222","errorCode":null,"errorMessage":"permalinks configuration invalid: unknown value %q for key %q","messagePattern":"permalinks configuration invalid: unknown value %q for key %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"resources/page/permalinks.go","lineNumber":597,"sourceCode":"\t\tcase hmaps.Params:\n\t\t\t// [permalinks.kind]\n\t\t\t//   section = '...'\n\t\t\tif !hstrings.InSlice(permalinksKindsSupport, k) {\n\t\t\t\treturn nil, fmt.Errorf(\"permalinks configuration not supported for kind %q, supported kinds are %v\", k, permalinksKindsSupport)\n\t\t\t}\n\t\t\tfor k2, v2 := range v {\n\t\t\t\tswitch v2 := v2.(type) {\n\t\t\t\tcase string:\n\t\t\t\t\tconfigs = append(configs,\n\t\t\t\t\t\tPermalinkConfig{Target: PageMatcher{Kind: k, Path: sectionToPathGlob(k2)}, Pattern: v2},\n\t\t\t\t\t)\n\t\t\t\tdefault:\n\t\t\t\t\treturn nil, fmt.Errorf(\"permalinks configuration invalid: unknown value %q for key %q for kind %q\", v2, k2, k)\n\t\t\t\t}\n\t\t\t}\n\n\t\tdefault:\n\t\t\treturn nil, fmt.Errorf(\"permalinks configuration invalid: unknown value %q for key %q\", v, k)\n\t\t}\n\t}\n\treturn configs, nil\n}\n","sourceCodeStart":579,"sourceCodeEnd":602,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/resources/page/permalinks.go#L579-L602","documentation":"Hugo throws this at the top-level permalinks switch when a value in the `permalinks` map is neither a string (old flat form) nor a params map (new `[permalinks.kind]` form). The decoder at permalinks.go:596-598 hits its `default` arm, meaning the config shape itself is unrecognizable. Build aborts during config load.","triggerScenarios":"A `permalinks` map entry whose value is a number, bool, array, or nil -- e.g. `permalinks = { posts = 5 }` in YAML, or a TOML `[permalinks]` with `posts = true`. Anything that is not a string and not a sub-table.","commonSituations":"YAML alias/anchor resolving to a non-string; empty value collapsing to nil; typo turning a pattern into a flag (`posts` instead of `posts = \"...\"`); migrating config between formats with a lossy converter.","solutions":["Ensure each top-level `permalinks` value is either a quoted string pattern or a sub-table of section-to-string entries.","Run `hugo config` and grep for `permalinks` to inspect the decoded structure.","If using YAML, quote patterns explicitly to avoid implicit type coercion.","Strip any null/empty entries from the permalinks map."],"exampleFix":"# config.yaml -- before\npermalinks:\n  posts:\n\n# after\npermalinks:\n  posts: /posts/:slug/","handlingStrategy":"validation","validationCode":"// Validate that every top-level permalinks value is string or map[string]any.\nfunc validatePermalinksTop(m map[string]any) error {\n\tfor k, v := range m {\n\t\tswitch v.(type) {\n\t\tcase string, map[string]any:\n\t\tdefault:\n\t\t\treturn fmt.Errorf(\"permalinks[%q] must be string or table, got %T\", k, v)\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use TOML tables (`[permalinks.page]`) to make structure explicit.","Run `hugo config` after config edits to catch type errors early.","Avoid YAML anchors in permalinks -- they can resolve to non-string types."],"tags":["config","permalinks","hugo","yaml","validation"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}