gohugoio/hugo · error

permalinks configuration not supported for kind %q, supporte

Error message

permalinks configuration not supported for kind %q, supported kinds are %v

What it means

The legacy nested map form `[permalinks.<kind>]` only supports the page kinds page, home, section, taxonomy, and term (permalinksKindsSupport). decodePermalinksMap raises this error when the second-level key is a map but its name is not one of those kinds, listing the supported values. It prevents silently ignoring permalink rules that could never match.

Source

Thrown at resources/page/permalinks.go:583

	var configs PermalinksConfig
	config := hmaps.CleanConfigStringMap(m)

	for k, v := range config {
		switch v := v.(type) {
		case string:
			// [permalinks]
			//   key = '...'
			// Backward compat: set for both page and term.
			configs = append(configs,
				PermalinkConfig{Target: PageMatcher{Kind: kinds.KindPage, Path: sectionToPathGlob(k)}, Pattern: v},
				PermalinkConfig{Target: PageMatcher{Kind: kinds.KindTerm, Path: sectionToPathGlob(k)}, Pattern: v},
			)

		case hmaps.Params:
			// [permalinks.kind]
			//   section = '...'
			if !hstrings.InSlice(permalinksKindsSupport, k) {
				return nil, fmt.Errorf("permalinks configuration not supported for kind %q, supported kinds are %v", k, permalinksKindsSupport)
			}
			for k2, v2 := range v {
				switch v2 := v2.(type) {
				case string:
					configs = append(configs,
						PermalinkConfig{Target: PageMatcher{Kind: k, Path: sectionToPathGlob(k2)}, Pattern: v2},
					)
				default:
					return nil, fmt.Errorf("permalinks configuration invalid: unknown value %q for key %q for kind %q", v2, k2, k)
				}
			}

		default:
			return nil, fmt.Errorf("permalinks configuration invalid: unknown value %q for key %q", v, k)
		}
	}
	return configs, nil
}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Use one of the supported kinds: `[permalinks.page]`, `[permalinks.section]`, `[permalinks.term]`, `[permalinks.taxonomy]`, `[permalinks.home]`.
2. If you meant a content section, put it as a key directly under `[permalinks]` with a string value: `posts = '/:year/:slug/'`.
3. Fix plural/typo kind names (e.g. `terms` → `term`).

Example fix

# before
[permalinks.posts]
tutorials = "/:year/:slug/"

# after
[permalinks.page]
posts = "/:year/:slug/"

supported := map[string]bool{"page": true, "section": true, "taxonomy": true, "term": true}
if !supported[kind] { /* fix config key */ }

When it happens

Trigger: Config like `[permalinks.posts.subsection]` or `[permalinks.pages]` — any `[permalinks.X]` table where X is not page/home/section/taxonomy/term; e.g. using a section name as the kind level with a nested table under it.

Common situations: Confusing the kind-scoped format (`[permalinks.page]`) with the simple section format (`[permalinks]\nposts = ...`); typos like `sections` or `terms` (plural); older docs/examples using taxonomy names as nested tables.

Related errors

• failed to compile permalink target %d: %w
• errPermalinkAttributeUnknown
• permalinks: unsupported config type %T
• permalinks: pattern must be a string, got %T
• permalinks: missing pattern

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