gohugoio/hugo · error

failed to create term page %q: %w

Error message

failed to create term page %q: %w

What it means

Raised in hugolib/content_map_page_assembler.go:873 while Hugo auto-generates taxonomy term pages. For each term collected from page front matter, Hugo builds a `pageMetaSource` of kind `term` and runs it through `transformPages`; if that transformation fails (cascade application, page-config validation, merging with an existing term page), the error is wrapped with the term's tree key (e.g. "/tags/foo").

Source

Thrown at hugolib/content_map_page_assembler.go:873

						},
					)
				}

				if len(v) > 0 {
					p := &pageMetaSource{
						pathInfo:        pi,
						sitesMatrixBase: v,
						pageConfigSource: &pagemeta.PageConfigEarly{
							Kind: kinds.KindTerm,
						},
					}
					var n2 contentNode = p
					if found {
						n2 = contentNodes{n, p}
					}
					n2, ns, err := transformPages(termKey, n2, getCascades(pw.WalkContext, termKey))
					if err != nil {
						return fmt.Errorf("failed to create term page %q: %w", termKey, err)
					}

					switch ns {
					case doctree.NodeTransformStateReplaced:
						pw.Tree.InsertRaw(termKey, n2)
					}

				}
			}
			return nil
		},
	)

	pw.Transform = func(s string, n contentNode) (n2 contentNode, ns doctree.NodeTransformState, err error) {
		n2, ns, err = transformPagesAndCreateMissingStructuralNodes(s, n, false)

		if err != nil || ns >= doctree.NodeTransformStateSkip {
			return

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Look at the quoted term key in the error to identify which taxonomy term failed, then inspect the wrapped cause after the colon.
2. Fix the front matter of that term's `_index.md` (if one exists) or the cascade that applies to term pages.
3. Check pages that declare the term in front matter for non-string/odd values (e.g. a map where a string is expected in `tags`).

Example fix

# before (content/tags/_index.md)
---
cascade:
  outputs: [bogus-format]
---

# after
---
cascade:
  outputs: [html, rss]
---

hugo --logLevel info  # check taxonomy warnings; ensure taxonomy terms are plain strings, not maps/objects

if err := hugolib.Build(...); err != nil {
    log.Fatalf("term page creation failed (check the quoted term's front matter and _index.md): %v", err)
}

When it happens

Trigger: Builds of sites with taxonomies where creating or merging a specific term page fails — e.g. a cascade targeting term pages carries invalid values, a manually created term page (content/tags/foo/_index.md) has bad front matter that conflicts during merge, or the term key itself produces an invalid page config.

Common situations: Invalid `cascade` blocks in taxonomy `_index.md` files or site config that apply to term pages; malformed front matter in a term's own `_index.md`; unusual term values in page front matter (odd characters/types) producing bad paths; regressions after changing taxonomy config.

Related errors

• error building site: %w
• failed to create page from pageMetaSource %s: %w
• failed to create page from file %q: %w
• failed to create page meta from file %q: %w
• no taxonomy configuration found for %q

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