gohugoio/hugo · error

permalink attribute not recognised

Error message

permalink attribute not recognised

What it means

Permalink patterns use `:attr` tokens expanded from a fixed map (`knownPermalinkAttributes` at permalinks.go:113-131: year/month/monthname/day/weekday/weekdayname/yearday/section/sectionslug/sections/sectionslugs/title/slug/slugorfilename/filename/contentbasename/slugorcontentbasename). During pattern compilation, any token not in that map yields this error wrapped as `error expanding ...` (permalinks.go:228).

Source

Thrown at resources/page/permalinks.go:272

	})
}

// pageToPermaAttribute is the type of a function which, given a page and a tag
// can return a string to go in that position in the page (or an error)
type pageToPermaAttribute func(Page, string) (string, error)

var attributeRegexp = regexp.MustCompile(`:\w+(\[.+?\])?`)

type permalinkExpandError struct {
	pattern string
	err     error
}

func (pee *permalinkExpandError) Error() string {
	return fmt.Sprintf("error expanding %q: %s", pee.pattern, pee.err)
}

var errPermalinkAttributeUnknown = errors.New("permalink attribute not recognised")

func (l PermalinkExpander) pageToPermalinkDate(p Page, dateField string) (string, error) {
	// a Page contains a Node which provides a field Date, time.Time
	switch dateField {
	case "year":
		return strconv.Itoa(p.Date().Year()), nil
	case "month":
		return fmt.Sprintf("%02d", int(p.Date().Month())), nil
	case "monthname":
		return p.Date().Month().String(), nil
	case "day":
		return fmt.Sprintf("%02d", p.Date().Day()), nil
	case "weekday":
		return strconv.Itoa(int(p.Date().Weekday())), nil
	case "weekdayname":
		return p.Date().Weekday().String(), nil
	case "yearday":
		return strconv.Itoa(p.Date().YearDay()), nil

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Use only the documented `:attributes` (year, month, day, section, title, slug, filename, sections, sectionslug, sectionslugs, contentbasename, slugorfilename, slugorcontentbasename, etc.).
2. For custom params/taxonomies, build URLs differently — permalink attributes don't expand arbitrary params.
3. Fix typos in attribute names.

Example fix

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

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

valid := map[string]bool{"year":true,"month":true,"monthname":true,"day":true,"weekday":true,"weekdayname":true,"yearday":true,"section":true,"sectionslug":true,"sections":true,"sectionslugs":true,"title":true,"slug":true,"slugorfilename":true,"filename":true,"contentbasename":true,"slugorcontentbasename":true}
for _, m := range attributeRegexp.FindAllStringSubmatch(pattern, -1) {
    name := strings.TrimPrefix(m[0], ":")
    if i := strings.IndexByte(name, '['); i >= 0 { name = name[:i] }
    if !valid[name] { return fmt.Errorf("permalink attribute %q not recognised", name) }
}

When it happens

Trigger: Configuring `permalinks` in hugo.toml with a pattern containing an unknown `:token`, e.g. `:author` or `:category` (note: taxonomies are not permalink attributes), or a typo like `:sectoin`.

Common situations: Assuming taxonomy terms are available as `:tag`/`:category`; typo in a known attribute; following an outdated doc listing different tokens; trying to reference a custom param via `:myparam`.

Related errors

• permalinks: missing pattern
• permalinks configuration not supported for kind %q, supporte
• cardinalityThreshold threshold must be between 0 and 100
• markup must not be set, use mediaType
• failed to compile permalink target %d: %w

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