gohugoio/hugo · error

failed to create page from pageMetaSource

Error message

failed to create page from pageMetaSource %s: %w

What it means

Returned inside transformPages' handleContentNodeSeq when handlePageMetaSource fails for one pageMetaSource in a contentNodeSeq (a sequence of page sources for the same path, e.g. multi-language or multi-version). The path key s is included. This is the multi-source branch where each source in the sequence is turned into a concrete page node.

Solutions

1. Unwrap the %w to find which source and which cause failed; the path key s identifies the tree location.
2. Inspect every pageMetaSource variant at that path (all languages/versions) for front-matter or config issues.
3. For content-adapter-generated sources, validate PageConfigEarly before emission.
4. Isolate by building a single language/version at a time to find the failing variant.

func validateAllVariants(sources []*pageMetaSource) error {
    for _, s := range sources {
        if err := s.pageConfigSource.CompileForPagesFromDataPre(base, log, mediaTypes); err != nil { return err }
    }
    return nil
}

if _, _, err := transformPages(s, n, getCascades(...)); err != nil {
    if strings.Contains(err.Error(), "failed to create page from pageMetaSource") {
        // build one language/version at a time to isolate the failing variant
    }
}

When it happens

Trigger: During the page-assembly transform pass, one of several pageMetaSource objects sharing a tree key fails to resolve into a pageState — front matter invalid, path info bad, site vector conflict, or page-config compilation error. Common with multilingual/multi-version content where one language/version is broken.

Common situations: One translation in a multilingual bundle has invalid front matter; a content adapter produces a bad PageConfigEarly for one variant; version (e.g. draft/published) specific config error; sitesmatrix vector conflict between bundled sources.

Related errors

• failed to create page from file
• failed to create page meta from file
• failed to create term page
• contentNodeToContentNodesPage: unexpected type %T
• missing taxonomy

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

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