gohugoio/hugo · error

missing taxonomy: %s

Error message

missing taxonomy: %s

What it means

Raised in pageMap.CreateSiteTaxonomies (hugolib/content_map_page.go:1189) while walking term pages: a page of kind 'term' was found under a taxonomy view whose entry is missing from the taxonomies map being built. Since the map is seeded from the configured taxonomy views just above, hitting this indicates an inconsistency between the configured taxonomies and the term pages present in the content tree — essentially an internal invariant violation surfaced as an error rather than a panic.

Source

Thrown at hugolib/content_map_page.go:1189

	for _, viewName := range m.cfg.taxonomyConfig.views {
		key := viewName.pluralTreeKey
		taxonomies[viewName.plural] = make(page.Taxonomy)
		w := &doctree.NodeShiftTreeWalker[contentNode]{
			Tree:     m.treePages,
			Prefix:   paths.AddTrailingSlash(key),
			LockType: doctree.LockTypeRead,
			Handle: func(s string, n contentNode) (radix.WalkFlag, error) {
				p := n.(*pageState)

				switch p.Kind() {
				case kinds.KindTerm:
					if !p.m.shouldList(true) {
						return radix.WalkContinue, nil
					}
					taxonomy := taxonomies[viewName.plural]
					if taxonomy == nil {
						return radix.WalkStop, fmt.Errorf("missing taxonomy: %s", viewName.plural)
					}
					if p.m.term == "" {
						panic("term is empty")
					}
					k := strings.ToLower(p.m.term)

					err := m.treeTaxonomyEntries.WalkPrefix(
						doctree.LockTypeRead,
						paths.AddTrailingSlash(s),
						func(ss string, wn *weightedContentNode) (bool, error) {
							taxonomy[k] = append(taxonomy[k], page.NewWeightedPage(wn.weight, wn.n.(page.Page), wn.term.Page()))
							return false, nil
						},
					)
					if err != nil {
						return radix.WalkStop, err
					}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Check [taxonomies] in your site config: every taxonomy your content uses must be declared with consistent singular/plural forms.
2. If you recently changed taxonomy config or disableKinds, restart 'hugo server' (or run a clean build with 'hugo --gc') to rebuild the content map.
3. Remove or update front matter referencing a taxonomy you deleted from configuration.
4. If config and content are consistent and the error persists, report it as a bug to the Hugo repo with a minimal reproducer.

Example fix

# before (hugo.toml) — taxonomy removed but term pages remain referenced
[taxonomies]
category = 'categories'

# after — declare all taxonomies your content uses
[taxonomies]
category = 'categories'
tag = 'tags'

// Ensure every taxonomy referenced in content is declared in hugo.toml
[taxonomies]
  tag = "tags"
  category = "categories"
// and check front matter keys match the plural names configured above

When it happens

Trigger: During site build when CreateSiteTaxonomies walks tree entries under a taxonomy's plural key and taxonomies[viewName.plural] is nil — e.g. taxonomy configuration and the page tree disagree about which taxonomy views exist.

Common situations: Unusual taxonomy configuration edits (renaming a taxonomy's plural form, disabling taxonomies via disableKinds while term pages still exist), stale content structures after config changes in hugo server without a restart, or a genuine Hugo bug in taxonomy bookkeeping.

Related errors

• failed to create term page %q: %w
• no taxonomy configuration found for %q
• error copying static files: %w
• error building site: %w
• failed to compile cache buster %q: %w

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