What causes "permalinks: missing pattern" in gohugoio/hugo?

Add a 'pattern' key to every [[permalinks]] entry.

permalinks: missing pattern

Error message

permalinks: missing pattern

What it means

Thrown by decodePermalinksSlice when a permalink rule map has no 'pattern' key at all. Every rule in the list format must declare a pattern; this fires in the else branch when the key lookup fails.

Solutions

Add a 'pattern' key to every [[permalinks]] entry.
Check for typos in the key name (it must be exactly 'pattern').
Run 'hugo' and fix each rule flagged by the error.

Example fix

# before
[[permalinks]]
target = { path = "/posts/**" }
# after
[[permalinks]]
target = { path = "/posts/**" }
pattern = "/:year/:slug/"

Defensive patterns

Strategy: validation

Validate before calling

if _, ok := m["pattern"]; !ok {
    return errors.New("permalinks rule missing pattern")
}

Try / catch

cfg, err := page.DecodePermalinksConfig(raw)
if err != nil { /* add the missing pattern key */ }

Prevention

Ensure every [[permalinks]] entry has a 'pattern' key.
Watch for typos like 'patten' or 'patterns'.
Run 'hugo' to catch missing keys at startup.

When it happens

Trigger: A [[permalinks]] entry that only sets 'target' and omits 'pattern', or a typo like 'patten' that leaves the real key absent.

Common situations: Hand-editing the permalinks list and forgetting the pattern line, or copy-pasting a partial rule.

Related errors

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

Appendix: 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 52c9bd7908)