gohugoio/hugo · error
empty path is reserved for the home page
Error message
empty path is reserved for the home page
What it means
For pages created from data via content adapters (pagesFromData), PageConfigEarly.Init trims the leading slash from the given path and requires the result to be non-empty unless the page kind is explicitly 'home'. An empty path maps to the site root, which is reserved for the home page, so Hugo rejects it to prevent accidentally overwriting or shadowing the home page.
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 8a468df065)
Solutions
- Ensure every .AddPage call passes a non-empty path; guard against blank slugs from your data source before calling AddPage.
- If you genuinely intend to define the home page from data, set "kind" to "home" in the page dict.
- Validate/skip records with missing path fields and warnf so the build surfaces them.
Example fix
{{/* before */}}
{{ .AddPage (dict "path" $item.slug "title" $item.title) }}
{{/* after */}}
{{ if $item.slug }}
{{ .AddPage (dict "path" $item.slug "title" $item.title) }}
{{ else }}
{{ warnf "skipping item without slug: %v" $item.title }}
{{ end }} Defensive patterns
Strategy: validation
Validate before calling
# front matter: don't set path to empty string --- path: "/about" # never path: "" ---
Prevention
- Omit `path` entirely instead of setting it to an empty string
- Only _index.md at content root may represent the home page
- Audit archetypes/scripts that generate front matter so they never emit `path: ""`
When it happens
Trigger: A content adapter (_content.gotmpl) calling .AddPage with path "" or "/" while kind is not "home", e.g. {{ .AddPage (dict "path" "" "title" "X") }}.
Common situations: Content adapters building paths from data where a field is empty/missing (e.g. slug from an API record is blank); generating the root page from data without setting kind = "home"; string manipulation leaving a bare "/".
Related errors
- alias "" is an empty string
- error processing file %q
- failed to parse file %q: %s
- failed to convert metadata for file %q: %s
- redirects must have either From or FromRe set
AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31).
Data as JSON: /data/errors/c49d1326c234c746.json.
Report an issue: GitHub ↗.