gohugoio/hugo · error

failed to create page from pageMetaSource %s: %w

Error message

failed to create page from pageMetaSource %s: %w

What it means

Raised in hugolib/content_map_page_assembler.go:357 (and :369) during Hugo's page-assembly phase, wrapping an underlying failure from `handlePageMetaSource` — the step that turns a raw `pageMetaSource` (front matter + content source at a tree path) into a `pageState`. The `%s` is the content tree path; the wrapped error is the real cause, typically invalid front matter, a cascade/page-config validation error, or an output-format/kind problem.

Source

Thrown at hugolib/content_map_page_assembler.go:357

					}

				}
			default:
				panic(fmt.Sprintf("unexpected type %T", v))
			}

			return
		}

		// The common case.
		ns = doctree.NodeTransformStateReplaced

		handleContentNodeSeq := func(v contentNodeSeq) (contentNode, doctree.NodeTransformState, error) {
			is := make(contentNodesMap)
			for ms := range v {
				_, err := handlePageMetaSource(ms, is, false)
				if err != nil {
					return nil, 0, fmt.Errorf("failed to create page from pageMetaSource %s: %w", s, err)
				}
			}
			return is, ns, nil
		}

		switch v := n.(type) {
		case contentNodeSeq, contentNodes:
			return handleContentNodeSeq(cnh.contentNodeToSeq(v))
		case *pageMetaSource:
			n2, err = handlePageMetaSource(v, nil, false)
			if err != nil {
				return nil, 0, fmt.Errorf("failed to create page from pageMetaSource %s: %w", s, err)
			}
			return
		case *pageState:
			// Nothing to do.
			ns = doctree.NodeTransformStateNone
			return v, ns, nil

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Read the wrapped error after the colon — it names the real cause — and note the path printed in the message to locate the offending content file.
2. Fix that file's front matter (dates, outputs, kind, params) or the cascade block that applies to it.
3. If it appeared after a Hugo upgrade, check the release notes for stricter front-matter/config validation and adjust the content accordingly.

Example fix

# before (content/posts/foo.md)
---
title: Foo
date: 31/12/2025
---

# after
---
title: Foo
date: 2025-12-31
---

hugo --printPathWarnings --logLevel debug  # surface bad front matter / paths before the assembler fails

if err := hugolib.Build(...); err != nil {
    // wrapped error: inspect the %w cause chain
    log.Fatalf("page assembly failed: %v", err) // message names the offending pageMetaSource path
}

When it happens

Trigger: Any `hugo` build/server run where creating a page from its metadata source fails: unparseable or semantically invalid front matter (bad dates, invalid `outputs`, unknown kind), failing cascade application, or errors in early page-config decoding for a specific content file.

Common situations: A malformed front matter field in one content file (e.g. `date: not-a-date`), invalid values injected via `cascade` in a section's front matter or site config, or content produced by templates/imports with bad metadata; can appear after upgrading Hugo when previously-lenient front matter becomes an error.

Related errors

• error processing file %q
• error building site: %w
• the %q front matter field is not a parsable date: see %s
• failed to create term page %q: %w
• alias "%s" resolves to website root directory

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