What causes "empty path is reserved for the home page" in gohugoio/hugo?

Set a non-empty Path on every pageConfig whose Kind is not 'home' (e.g. '/posts/my-post').

empty path is reserved for the home page

Error message

empty path is reserved for the home page

What it means

Thrown by PageConfigEarly.Init when a page is created from data (a content adapter, pagesFromData=true) and its canonical Path is empty while its Kind is not 'home'. An empty path is reserved exclusively for the home page, so any other kind must declare a non-empty path.

Solutions

Set a non-empty Path on every pageConfig whose Kind is not 'home' (e.g. '/posts/my-post').
If the page is meant to be the home page, set Kind explicitly to 'home'.
Ensure your content adapter computes the path before calling AddPage so it is never empty.

Example fix

// before
pcfg := &pagemeta.PageConfigEarly{Kind: kinds.KindPage}
err := pcfg.Init(true)
// after
pcfg := &pagemeta.PageConfigEarly{Kind: kinds.KindPage, Path: "/posts/hello"}
err := pcfg.Init(true)

Defensive patterns

Strategy: validation

Validate before calling

if pagesFromData && p.Path == "" && p.Kind != kinds.KindHome {
    return errors.New("non-home data page needs a path")
}

Try / catch

if err := pcfg.Init(true); err != nil {
    return fmt.Errorf("adapter page config: %w", err)
}

Prevention

Always set Path on non-home pages created by content adapters.
Reserve empty Path for the home page only.
Compute paths before calling AddPage in adapters.

When it happens

Trigger: A content adapter's AddPages callback (or a data-driven page) creates a page whose Path is unset/empty but whose Kind is e.g. 'page', 'section', or a taxonomy term.

Common situations: Writing a custom content adapter and forgetting to set Path on the pageConfig, or setting Kind to something other than 'home' while leaving Path blank. Also when normalizing strips a leading slash and leaves nothing.

Related errors

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

Appendix: source

Thrown at resources/page/pagemeta/page_frontmatter.go:237

	return p.MatchLanguageCoarse(siteVector) && p.MatchSiteVectorCoarseExcludeLanguage(siteVector)
}

func (p *SitesMatrixAndComplements) MatchSiteVectorCoarseExcludeLanguage(siteVector sitesmatrix.Vector) bool {
	return p.MatchRoleCoarse(siteVector) && p.MatchVersionCoarse(siteVector)
}

func DefaultPageConfig() *PageConfigLate {
	return &PageConfigLate{
		Build: DefaultBuildConfig,
	}
}

func (p *PageConfigEarly) Init(pagesFromData bool) error {
	if pagesFromData {
		p.Path = strings.TrimPrefix(p.Path, "/")

		if p.Path == "" && p.Kind != kinds.KindHome {
			return fmt.Errorf("empty path is reserved for the home page")
		}

		if p.Content.Markup != "" {
			return errors.New("markup must not be set, use mediaType")
		}
	}

	return nil
}

func (p *PageConfigLate) Init() error {
	return nil
}

func buildSitesComplementsFromSitesConfig(
	conf config.AllProvider,
	fim *hugofs.FileMeta,
	sitesConfig sitesmatrix.Sites,

View on GitHub (pinned to 52c9bd7908)