gohugoio/hugo · error

alias "%s" resolves to website root directory

Error message

alias "%s" resolves to website root directory

What it means

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).

Source

Thrown at hugolib/alias.go:132

	}

	if s.conf.RelativeURLs || s.conf.CanonifyURLs {
		pd.AbsURLPath = s.absURLPath(targetPath)
	}

	return s.publisher.Publish(pd)
}

func (a aliasHandler) targetPathAlias(src string, of output.Format) (string, error) {
	originalAlias := src
	if len(src) <= 0 {
		return "", fmt.Errorf("alias \"\" is an empty string")
	}

	alias := path.Clean(filepath.ToSlash(src))

	if !a.allowRoot && alias == "/" {
		return "", fmt.Errorf("alias \"%s\" resolves to website root directory", originalAlias)
	}

	components := strings.Split(alias, "/")

	// Validate against directory traversal
	if components[0] == ".." {
		return "", fmt.Errorf("alias \"%s\" traverses outside the website root directory", originalAlias)
	}

	// Handle Windows file and directory naming restrictions
	// See "Naming Files, Paths, and Namespaces" on MSDN
	// https://msdn.microsoft.com/en-us/library/aa365247%28v=VS.85%29.aspx?f=255&MSPPError=-2147217396
	msgs := []string{}
	reservedNames := []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"}

	if strings.ContainsAny(alias, ":*?\"<>|") {
		msgs = append(msgs, fmt.Sprintf("Alias \"%s\" contains invalid characters on Windows: : * ? \" < > |", originalAlias))
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Remove the "/" entry from that page's `aliases` front matter — a page cannot alias the site root.
2. 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.
3. 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.
4. Check for computed alias values (e.g. from cascade or archetypes) that unintentionally clean to "/".

Example fix

# before (content/new-home.md)
---
title: New Home
aliases: ["/"]
---

# after
---
title: New Home
url: /
---

// Go: reject aliases that resolve to the site root before building
func validAlias(a string) bool {
    clean := path.Clean(filepath.ToSlash(a))
    return clean != "/" && clean != "." && clean != ""
}

if err := site.Build(); err != nil && strings.Contains(err.Error(), "resolves to website root") {
    // report the offending page's aliases front matter
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• alias "%s" traverses outside the website root directory
• failed to create page from pageMetaSource %s: %w
• http* aliases not supported: %q
• error processing file %q
• failed to parse file %q: %s

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/6a5dec94d920c1cf.json. Report an issue: GitHub ↗.