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

Fix the front matter of the file named in the error message; the wrapped error identifies the exact parse failure.

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

Error message

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

What it means

In the default branch of pageMap.AddFi — a standalone (non-bundled, non-data) content file — Hugo builds page metadata via newPageMetaSourceFromFile and wraps any failure with the filename. Like the bundled variant, it means a file on the content walk could not be parsed into a page, and the wrapped error carries the root cause.

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 8a468df065)

Solutions

Fix the front matter of the file named in the error message; the wrapped error identifies the exact parse failure.
Validate structured front matter fields (date, cascade, build, aliases) against the current Hugo version's schema — upgrades can turn warnings into errors.
Verify the file is readable and valid UTF-8 (re-save without BOM/UTF-16 if a sync tool mangled it).

Example fix

// before (content/about.md)
+++
title = "About"
---
// after
+++
title = "About"
+++

Defensive patterns

Strategy: try-catch

Validate before calling

// lint front matter of the named file before building
content, err := os.ReadFile(path)
if err != nil { return err }
if _, err := pageparser.ParseBytes(content, pageparser.Config{}); err != nil {
    return fmt.Errorf("front matter in %q: %w", path, err)
}

Try / catch

if err := site.Build(); err != nil {
    if strings.Contains(err.Error(), "failed to create page meta") {
        // the wrapped cause is a front matter/metadata problem in the quoted file
    }
    return err
}

Prevention

Errors here are almost always front matter metadata: wrong types (string where date expected), bad cascade blocks, invalid aliases
Run a full `hugo` build in CI on every content change
Use archetypes so new pages start with known-good front matter

When it happens

Trigger: During hugo build/server, a top-level content file (e.g. content/posts/foo.md, _index.md) fails page-meta creation: unparseable front matter, invalid front matter values (dates, cascade, build options), or I/O errors opening the source file.

Common situations: Broken YAML/TOML front matter in a regular page or _index.md; invalid cascade or build blocks after a Hugo upgrade tightened validation; wrong front matter delimiter mix (--- opening, +++ closing); files corrupted by editors or sync tools.

Related errors

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