gohugoio/hugo · error

failed to create page from file %q: %w

Error message

failed to create page from file %q: %w

What it means

In pageMap.AddFi's insertResource closure, a bundled content file (a content-typed file inside a page bundle) is turned into page metadata via newPageMetaSourceFromFile; if that fails, the error is wrapped with the source filename and aborts the build walk. It means Hugo found a content file in a bundle but could not parse it into a page — almost always a front matter problem.

Source

Thrown at hugolib/content_map.go:263

	if m == nil {
		panic("nil pageMap")
	}

	h := m.s.h

	insertResource := func(fim hugofs.FileMetaInfo) error {
		resourceSourceCount++
		pi := fi.Meta().PathInfo
		key := pi.Base()
		tree := m.treeResources

		tree.Lock(true)
		defer tree.Unlock(true)

		if pi.IsContent() {
			pm, err := h.newPageMetaSourceFromFile(fi)
			if err != nil {
				return fmt.Errorf("failed to create page from file %q: %w", fi.Meta().Filename, err)
			}
			pm.bundled = true
			m.treeResources.Insert(key, pm)
		} else {
			r := func() (hugio.ReadSeekCloser, error) {
				return fim.Meta().Open()
			}
			// Create one dimension now, the rest later on demand.
			rs := &resourceSource{path: pi, opener: r, fi: fim, sv: fim.Meta().SitesMatrix.VectorSample()}
			m.treeResources.Insert(key, rs)
		}

		return nil
	}

	meta := fi.Meta()
	pi := meta.PathInfo

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Open the file named in the error and fix its front matter — check delimiters and validate the YAML/TOML syntax the wrapped error points at.
2. Check date/param values in front matter (invalid dates are a frequent wrapped cause).
3. If the file isn't meant to be a page, rename it to a non-content extension or move it out of the bundle so it's treated as a plain resource.

Example fix

// before (content/post/my-bundle/notes.md)
---
title: Notes
date: 2026-13-40
--
Body
// after
---
title: Notes
date: 2026-07-31
---
Body

// sanity-check the content file before the build touches it
fi, err := os.Stat(path)
if err != nil || fi.IsDir() {
    return fmt.Errorf("bad content file %q", path)
}

if err := build(); err != nil {
    // wrapped error: unwrap to find the root cause (front matter parse, bad date, etc.)
    fmt.Fprintf(os.Stderr, "content build failed: %v\n", err)
    var root error = err
    for errors.Unwrap(root) != nil { root = errors.Unwrap(root) }
    // report root alongside the quoted filename from the message
}

When it happens

Trigger: During the content walk (hugo build/server), a file recognized as content (pi.IsContent()) inside a leaf/branch bundle fails newPageMetaSourceFromFile — malformed front matter delimiters, invalid YAML/TOML/JSON front matter, invalid dates, or an unreadable file.

Common situations: A markdown file in a page bundle with broken front matter (missing closing --- or +++, tabs in YAML, invalid TOML date); merge-conflict markers in content files; files with a content extension that aren't actually content; encoding issues (UTF-16/BOM oddities) in bundled pages.

Related errors

• failed to create page meta from file %q: %w
• error building site: %w
• failed to create page from pageMetaSource %s: %w
• failed to create term page %q: %w
• error processing file %q

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