{"id":"6a5dec94d920c1cf","repo":"gohugoio/hugo","slug":"alias-s-resolves-to-website-root-directory","errorCode":null,"errorMessage":"alias \"%s\" resolves to website root directory","messagePattern":"alias \"(.+?)\" resolves to website root directory","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/alias.go","lineNumber":132,"sourceCode":"\t}\n\n\tif s.conf.RelativeURLs || s.conf.CanonifyURLs {\n\t\tpd.AbsURLPath = s.absURLPath(targetPath)\n\t}\n\n\treturn s.publisher.Publish(pd)\n}\n\nfunc (a aliasHandler) targetPathAlias(src string, of output.Format) (string, error) {\n\toriginalAlias := src\n\tif len(src) <= 0 {\n\t\treturn \"\", fmt.Errorf(\"alias \\\"\\\" is an empty string\")\n\t}\n\n\talias := path.Clean(filepath.ToSlash(src))\n\n\tif !a.allowRoot && alias == \"/\" {\n\t\treturn \"\", fmt.Errorf(\"alias \\\"%s\\\" resolves to website root directory\", originalAlias)\n\t}\n\n\tcomponents := strings.Split(alias, \"/\")\n\n\t// Validate against directory traversal\n\tif components[0] == \"..\" {\n\t\treturn \"\", fmt.Errorf(\"alias \\\"%s\\\" traverses outside the website root directory\", originalAlias)\n\t}\n\n\t// Handle Windows file and directory naming restrictions\n\t// See \"Naming Files, Paths, and Namespaces\" on MSDN\n\t// https://msdn.microsoft.com/en-us/library/aa365247%28v=VS.85%29.aspx?f=255&MSPPError=-2147217396\n\tmsgs := []string{}\n\treservedNames := []string{\"CON\", \"PRN\", \"AUX\", \"NUL\", \"COM0\", \"COM1\", \"COM2\", \"COM3\", \"COM4\", \"COM5\", \"COM6\", \"COM7\", \"COM8\", \"COM9\", \"LPT0\", \"LPT1\", \"LPT2\", \"LPT3\", \"LPT4\", \"LPT5\", \"LPT6\", \"LPT7\", \"LPT8\", \"LPT9\"}\n\n\tif strings.ContainsAny(alias, \":*?\\\"<>|\") {\n\t\tmsgs = append(msgs, fmt.Sprintf(\"Alias \\\"%s\\\" contains invalid characters on Windows: : * ? \\\" < > |\", originalAlias))\n\t}","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/alias.go#L114-L150","documentation":"Hugo's alias handler (aliasHandler.targetPathAlias in hugolib/alias.go) rejects an alias front matter value that, after path.Clean and slash normalization, resolves to \"/\" — the site root. Writing an alias redirect page at the root would overwrite or shadow the site's homepage index file, so Hugo refuses unless allowRoot is set (it is not for user-authored page aliases).","triggerScenarios":"A page's front matter contains `aliases: [\"/\"]`, or a value that cleans to \"/\" such as `aliases: [\"/foo/..\"]`, `aliases: [\".\"]`, or `aliases: [\"//\"]`. The error fires during site build when Hugo publishes alias redirect files for each alias entry.","commonSituations":"Migrating a site and trying to redirect the old homepage URL by aliasing \"/\" to a new page; templated front matter (archetypes or cascade) that computes an alias string that collapses to root; typo where the intended alias path segment was omitted leaving only the leading slash.","solutions":["Remove the \"/\" entry from that page's `aliases` front matter — a page cannot alias the site root.","If you want the root URL to serve this page, set `url: /` on the page (or make it the homepage content) instead of using an alias.","If you need a root-level redirect, implement it at the web server/CDN layer (netlify.toml redirects, nginx rewrite) rather than via Hugo aliases.","Check for computed alias values (e.g. from cascade or archetypes) that unintentionally clean to \"/\"."],"exampleFix":"# before (content/new-home.md)\n---\ntitle: New Home\naliases: [\"/\"]\n---\n\n# after\n---\ntitle: New Home\nurl: /\n---","handlingStrategy":"validation","validationCode":"// Go: reject aliases that resolve to the site root before building\nfunc validAlias(a string) bool {\n    clean := path.Clean(filepath.ToSlash(a))\n    return clean != \"/\" && clean != \".\" && clean != \"\"\n}","typeGuard":null,"tryCatchPattern":"if err := site.Build(); err != nil && strings.Contains(err.Error(), \"resolves to website root\") {\n    // report the offending page's aliases front matter\n}","preventionTips":["Never set `aliases: [\"/\"]` or an alias that cleans to the root in front matter","Lint front matter aliases in CI: path.Clean each alias and reject \"/\" or \".\"","Use redirects at the web-server level for root redirects instead of Hugo aliases"],"tags":["hugo","aliases","front-matter","build"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}