gohugoio/hugo · error

failed to create page from file

Error message

failed to create page from file %q: %w

What it means

Returned inside pageMap.AddFi's insertResource closure when newPageMetaSourceFromFile fails for a file classified as TypeContentResource (a bundled content file inside a page bundle, e.g. a leaf bundle's attached .md). The filename from fi.Meta().Filename is included. This is the bundled-resource page-meta creation path.

Solutions

1. Open the file named in the error and validate its front matter (YAML/TOML syntax, required fields).
2. Check the path info / extension is a recognized content type in the site's mediaTypes config.
3. If the file is not meant to be a content resource, move it out of the bundle or give it a non-content extension.
4. Unwrap the %w to get the specific newPageMetaSourceFromFile cause and address that.

func validateBundledContent(fi hugofs.FileMetaInfo) error {
    if !fi.Meta().PathInfo.IsContent() { return nil }
    // parse front matter to catch errors before Hugo's AddFi
    _, err := parseFrontMatterFromFile(fi.Meta().Filename)
    return err
}

func isBundledContentResource(fi hugofs.FileMetaInfo) bool {
    return !fi.IsDir() && fi.Meta().PathInfo != nil && fi.Meta().PathInfo.IsContent()
}

When it happens

Trigger: A file inside a page bundle (under /content/.../somebundle/) is content (IsContent() true) but its front matter or path metadata is invalid for newPageMetaSourceFromFile — bad date, invalid path info, unsupported media type, or malformed front matter that the page config compiler rejects.

Common situations: Adding a .md or other content file alongside a bundle's index with malformed front matter; a bundled content file with an extension Hugo parses but whose front matter is broken; renaming/moving bundle files leaving stale metadata; content adapter/generated content with invalid config.

Related errors

• failed to create page meta from file
• failed to create page from pageMetaSource
• alias "" is an empty string
• alias " " resolves to website root directory
• contentNodeToContentNodesPage: unexpected type %T

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

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