What causes "failed to create term page %q: %w" in gohugoio/hugo?

Create an explicit term page (content/ / /_index.md) to bypass auto-creation and control its front matter.

failed to create term page

Error message

failed to create term page %q: %w

What it means

Returned during the post-walk hook that creates missing taxonomy term pages, when transformPages fails for a synthesized term page (a term referenced by content but lacking its own _index.md). The termKey (base path of the term) is included. Hugo auto-creates term pages from seenTerms and this is where materialization of an auto term page fails.

Solutions

Create an explicit term page (content/<taxonomy>/<term>/_index.md) to bypass auto-creation and control its front matter.
Unwrap %w to find the inner transform cause; the termKey identifies which term.
Review cascade/front-matter defaults applied to taxonomy term pages.
Check taxonomy config and multilingual consistency for the affected taxonomy.

Example fix

# before: term 'foo' referenced but no page, auto-creation fails
content/posts/a.md  ->  tags: ["foo"]
# after: provide explicit term page
content/tags/foo/_index.md

Defensive patterns

Strategy: validation

Validate before calling

func ensureTermPage(taxonomy, term string) error {
    p := filepath.Join("content", taxonomy, term, "_index.md")
    if _, err := os.Stat(p); os.IsNotExist(err) {
        // pre-create to avoid auto-synthesis path; or validate cascade config
    }
    return nil
}

Try / catch

if err := w.Walk(ctx); err != nil {
    if strings.Contains(err.Error(), "failed to create term page") {
        // create explicit _index.md for the named termKey, then rebuild
    }
}

Prevention

Provide explicit term _index.md pages for terms you reference.
Keep taxonomy term cascade/front-matter defaults valid.
Verify multilingual taxonomy config consistency to avoid synthesis failures.

When it happens

Trigger: Content assigns a taxonomy term (e.g. tags: [foo]) but no term page exists, so Hugo synthesizes one; transformPages then fails for that synthesized pageMetaSource — invalid cascade, broken path, front-matter compilation error, or a sitesmatrix conflict for the term.

Common situations: A taxonomy term whose auto-generated page inherits a broken cascade/default; multilingual term with mismatched config across languages; content adapter referencing a term that triggers a failing template; taxonomy config change after content already references terms.

Related errors

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

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