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

Open the file named in the message and fix the front matter (use `hugo --logLevel debug` to see the wrapped cause).

failed to create page meta from file

Error message

failed to create page meta from file %q: %w

What it means

Returned by pageMap.AddFi in the default branch (a page bundle / TypeFile that is a content file) when newPageMetaSourceFromFile fails while inserting the bundle's main page source into treePages. Distinct from 312: this is the page itself, not a bundled resource. Includes fi.Meta().Filename.

Solutions

Open the file named in the message and fix the front matter (use `hugo --logLevel debug` to see the wrapped cause).
Validate the path does not contain characters rejected by the paths parser.
Confirm the page's listed output formats/media types exist in the site config.
For content-adapter pages, ensure PageConfigEarly compiles (valid dates, weights, paths).

Defensive patterns

Strategy: validation

Validate before calling

func validatePageFile(path string) error {
    fm, err := frontmatter.ParseFile(path)
    if err != nil { return err }
    return validatePageConfig(fm) // dates, weights, paths, output formats
}

Try / catch

if err := pageMap.AddFi(fi, cfg); err != nil {
    if strings.Contains(err.Error(), "failed to create page meta from file") {
        // unwrap to the newPageMetaSourceFromFile cause and fix front matter
    }
}

Prevention

Lint all /content front matter in CI before building.
Ensure output formats/media types referenced exist in config.
Watch for path characters the Hugo path parser rejects.

When it happens

Trigger: A top-level/section content file (index.md, _index.md, or a section file) fails page-meta source construction — invalid front matter, bad draft date, unparseable path, unsupported output format config, or media-type mismatch.

Common situations: Content authors commit a page with broken front matter; a CMS export emits invalid YAML/TOML; a path containing characters the path parser rejects; content adapter (data-driven) pages with invalid PageConfigEarly; Hugo upgrade tightening front-matter validation.

Related errors

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

Appendix: source

Thrown at hugolib/content_map.go:313

		pageSourceCount += pc
		resourceSourceCount += rc
		if err != nil {
			addErr = err
			return
		}

	default:
		m.s.Log.Trace(logg.StringFunc(
			func() string {
				return fmt.Sprintf("insert bundle: %q", fi.Meta().Filename)
			},
		))

		pageSourceCount++

		pm, err := h.newPageMetaSourceFromFile(fi)
		if err != nil {
			addErr = fmt.Errorf("failed to create page meta from file %q: %w", fi.Meta().Filename, err)
			return
		}

		m.treePages.InsertWithLock(pm.pathInfo.Base(), pm)
	}
	return
}

func (m *pageMap) addPagesFromGoTmplFi(fi hugofs.FileMetaInfo, buildConfig *BuildCfg) (pageCount uint64, resourceCount uint64, addErr error) {
	meta := fi.Meta()
	pi := meta.PathInfo

	m.s.Log.Trace(logg.StringFunc(
		func() string {
			return fmt.Sprintf("insert pages from data file: %q", fi.Meta().Filename)
		},
	))

View on GitHub (pinned to 52c9bd7908)