{"id":"c49d1326c234c746","repo":"gohugoio/hugo","slug":"empty-path-is-reserved-for-the-home-page","errorCode":null,"errorMessage":"empty path is reserved for the home page","messagePattern":"empty path is reserved for the home page","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"resources/page/pagemeta/page_frontmatter.go","lineNumber":237,"sourceCode":"\treturn p.MatchLanguageCoarse(siteVector) && p.MatchSiteVectorCoarseExcludeLanguage(siteVector)\n}\n\nfunc (p *SitesMatrixAndComplements) MatchSiteVectorCoarseExcludeLanguage(siteVector sitesmatrix.Vector) bool {\n\treturn p.MatchRoleCoarse(siteVector) && p.MatchVersionCoarse(siteVector)\n}\n\nfunc DefaultPageConfig() *PageConfigLate {\n\treturn &PageConfigLate{\n\t\tBuild: DefaultBuildConfig,\n\t}\n}\n\nfunc (p *PageConfigEarly) Init(pagesFromData bool) error {\n\tif pagesFromData {\n\t\tp.Path = strings.TrimPrefix(p.Path, \"/\")\n\n\t\tif p.Path == \"\" && p.Kind != kinds.KindHome {\n\t\t\treturn fmt.Errorf(\"empty path is reserved for the home page\")\n\t\t}\n\n\t\tif p.Content.Markup != \"\" {\n\t\t\treturn errors.New(\"markup must not be set, use mediaType\")\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc (p *PageConfigLate) Init() error {\n\treturn nil\n}\n\nfunc buildSitesComplementsFromSitesConfig(\n\tconf config.AllProvider,\n\tfim *hugofs.FileMeta,\n\tsitesConfig sitesmatrix.Sites,","sourceCodeStart":219,"sourceCodeEnd":255,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/resources/page/pagemeta/page_frontmatter.go#L219-L255","documentation":"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.","triggerScenarios":"A content adapter (_content.gotmpl) calling .AddPage with path \"\" or \"/\" while kind is not \"home\", e.g. {{ .AddPage (dict \"path\" \"\" \"title\" \"X\") }}.","commonSituations":"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 \"/\".","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."],"exampleFix":"{{/* before */}}\n{{ .AddPage (dict \"path\" $item.slug \"title\" $item.title) }}\n{{/* after */}}\n{{ if $item.slug }}\n  {{ .AddPage (dict \"path\" $item.slug \"title\" $item.title) }}\n{{ else }}\n  {{ warnf \"skipping item without slug: %v\" $item.title }}\n{{ end }}","handlingStrategy":"validation","validationCode":"# front matter: don't set path to empty string\n---\npath: \"/about\"   # never path: \"\"\n---","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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: \"\"`"],"tags":["content-adapter","front-matter","validation","hugo"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}