gohugoio/hugo · error

permalinks: missing pattern

Error message

permalinks: missing pattern

What it means

Every entry in the slice-based permalinks configuration must contain a `pattern` key; decodePermalinksSlice returns this error when an entry has no `pattern` at all. An entry with only a `target` (kind/path matcher) is meaningless without a pattern to apply, so Hugo fails fast at config decode.

Source

Thrown at resources/page/permalinks.go:555

	for _, m := range ms {
		m = hmaps.CleanConfigStringMap(m)
		var cfg PermalinkConfig

		if targetVal, ok := m["target"]; ok {
			if err := mapstructure.WeakDecode(targetVal, &cfg.Target); err != nil {
				return nil, fmt.Errorf("permalinks: failed to decode target: %w", err)
			}
			cfg.Target.Kind = strings.ToLower(cfg.Target.Kind)
			cfg.Target.Path = filepath.ToSlash(strings.ToLower(cfg.Target.Path))
		}

		if patternVal, ok := m["pattern"]; ok {
			cfg.Pattern, ok = patternVal.(string)
			if !ok {
				return nil, fmt.Errorf("permalinks: pattern must be a string, got %T", patternVal)
			}
		} else {
			return nil, fmt.Errorf("permalinks: missing pattern")
		}

		configs = append(configs, cfg)
	}

	return configs, nil
}

func decodePermalinksMap(m map[string]any) (PermalinksConfig, error) {
	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.

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Add a `pattern` string to each permalinks array entry.
2. Check for typos in the key name — it must be exactly `pattern` (case-insensitive config keys are cleaned, but the key must be present).
3. Remove empty/stub permalinks entries.

Example fix

# before
[[permalinks]]
[permalinks.target]
kind = "page"
path = "/posts/**"

# after
[[permalinks]]
pattern = "/:year/:slug/"
[permalinks.target]
kind = "page"
path = "/posts/**"

if pattern == "" { return fmt.Errorf("permalink pattern for %q is empty", section) }

When it happens

Trigger: An `[[permalinks]]` array entry (TOML) or list item (YAML) that defines `target` or other keys but omits `pattern`; a misspelled key like `patern` or `Pattern` nested wrongly.

Common situations: Partially written config while migrating from the legacy map format; copy-paste of a target block without its pattern; key typos that survive because unknown keys are ignored.

Related errors

• failed to compile permalink target %d: %w
• errPermalinkAttributeUnknown
• permalinks: unsupported config type %T
• permalinks: pattern must be a string, got %T
• permalinks configuration not supported for kind %q, supporte

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