gohugoio/hugo · error

no taxonomy configuration found for %q

Error message

no taxonomy configuration found for %q

What it means

pageMeta.initLate resolves the taxonomy view for pages of kind taxonomy or term by prefix-matching the page path against the configured taxonomies (getTaxonomyConfig). If no configured taxonomy matches the path, Hugo cannot determine the singular/plural names or the term, so it fails. It means a taxonomy/term page exists for a taxonomy the site config doesn't declare.

Source

Thrown at hugolib/page__meta.go:323

			m.pathInfo = m.f.FileInfo().Meta().PathInfo
		}

		if m.pathInfo == nil {
			panic(fmt.Sprintf("missing pathInfo in %v", m))
		}
	}
	return nil
}

func (m *pageMeta) initLate(s *Site) error {
	var tc viewName

	if m.pageConfigSource.Kind == kinds.KindTerm || m.pageConfigSource.Kind == kinds.KindTaxonomy {
		if tc.IsZero() {
			tc = s.pageMap.cfg.getTaxonomyConfig(m.Path())
		}
		if tc.IsZero() {
			return fmt.Errorf("no taxonomy configuration found for %q", m.Path())
		}
		m.singular = tc.singular

		if m.pageConfigSource.Kind == kinds.KindTerm {
			m.term = paths.TrimLeading(strings.TrimPrefix(m.pathInfo.Unnormalized().Base(), "/"+tc.plural))
		}
	}

	return nil
}

// bookmark1
func (h *HugoSites) newPageMetaSourceFromFile(fi hugofs.FileMetaInfo) (*pageMetaSource, error) {
	p, err := func() (*pageMetaSource, error) {
		meta := fi.Meta()
		openSource := func() (hugio.ReadSeekCloser, error) {
			r, err := meta.Open()
			if err != nil {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Declare the taxonomy in site config so it matches the page path, e.g. `[taxonomies]\n tag = "tags"` in hugo.toml.
2. If the taxonomy was intentionally removed, delete or rename the stale content/<plural>/ directory (its _index.md pages) too.
3. If the page shouldn't be a taxonomy/term page, remove the explicit `kind` override in its front matter or content adapter.

Example fix

# before (hugo.toml)
[taxonomies]
  category = "categories"
# content/tags/_index.md exists -> error
# after
[taxonomies]
  category = "categories"
  tag = "tags"

// site config must declare every taxonomy referenced in front matter
// hugo.toml:
// [taxonomies]
//   tag = 'tags'
//   category = 'categories'
// check: front matter keys like `tags:`/`categories:` must map to an entry above

if err := site.Build(); err != nil {
    if strings.Contains(err.Error(), "no taxonomy configuration found") {
        // add the missing taxonomy to [taxonomies] in site config, or remove the front matter key
    }
    return err
}

When it happens

Trigger: A page is assigned KindTaxonomy or KindTerm — via content files like content/tags/_index.md when "tags" isn't in the taxonomies config, via a content adapter or front matter forcing kind: term/taxonomy, or after removing/renaming a taxonomy in config while its _index.md pages remain — and getTaxonomyConfig finds no view whose pluralTreeKey prefixes the page path.

Common situations: Setting `disableKinds` or a custom `taxonomies` block in hugo.toml that removes the default tags/categories while content/tags/_index.md still exists; renaming a taxonomy (e.g. tags → topics) in config without moving the content directory; theme-provided term pages for taxonomies the site never enabled.

Related errors

• failed to create term page %q: %w
• missing taxonomy: %s
• 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/f19dee40ee006ce7.json. Report an issue: GitHub ↗.