{"record":{"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/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/resources/page/pagemeta/page_frontmatter.go#L219-L255","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\npcfg := &pagemeta.PageConfigEarly{Kind: kinds.KindPage}\nerr := pcfg.Init(true)\n// after\npcfg := &pagemeta.PageConfigEarly{Kind: kinds.KindPage, Path: \"/posts/hello\"}\nerr := pcfg.Init(true)","handlingStrategy":"validation","validationCode":"if pagesFromData && p.Path == \"\" && p.Kind != kinds.KindHome {\n    return errors.New(\"non-home data page needs a path\")\n}","typeGuard":null,"tryCatchPattern":"if err := pcfg.Init(true); err != nil {\n    return fmt.Errorf(\"adapter page config: %w\", err)\n}","preventionTips":["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."],"tags":["hugo","content-adapter","page-config","paths","validation"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}