gohugoio/hugo · warning

alias "" is an empty string

Error message

alias "" is an empty string

What it means

Returned by aliasHandler.targetPathAlias (hugolib/alias.go) when the alias source string passed in is empty (len(src) <= 0). Aliases come from page front matter (the 'aliases' / 'alias' array) or redirects; an empty entry cannot map to a target file and is rejected outright.

Solutions

1. Search the content tree for aliases: entries containing an empty string and remove them.
2. If aliases are generated by a template/shortcode, guard so empty values are not emitted into front matter.
3. Validate front matter with a linter (e.g. hugo --renderToMemory plus a YAML lint) before building.
4. Audit any custom code calling Site.publishDestAlias/writeDestAlias to never pass an empty path.

Example fix

+++
# before
aliases = ["", "/posts/old-url/"]
# after
aliases = ["/posts/old-url/"]
+++

func validAliases(as []string) error {
    for _, a := range as {
        if strings.TrimSpace(a) == "" { return fmt.Errorf("empty alias") }
    }
    return nil
}

When it happens

Trigger: A page's front matter contains an empty alias string, e.g. aliases: ["", "/old/"] or aliases: [] with a stray empty element produced by a template generating front matter. Also any programmatic call to publishDestAlias/writeDestAlias with an empty path argument.

Common situations: Content authors hand-editing front matter and leaving a blank list item; a headless CMS or generator emitting aliases: [""]; migrating from 'alias' (singular, deprecated) to 'aliases' and leaving an empty value; templated content where the alias variable resolves to empty.

Related errors

• alias " " resolves to website root directory
• alias " " traverses outside the website root directory
• cannot create " ": Windows filename restriction
• failed to create page from file
• failed to create page meta from file

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/f4115c0dc3c07ed2. Report an issue: GitHub.

Appendix: source

Thrown at hugolib/alias.go:126

	pd := publisher.Descriptor{
		Src:          aliasContent,
		TargetPath:   targetPath,
		StatCounter:  &s.PathSpec.ProcessingStats.Aliases,
		OutputFormat: outputFormat,
	}

	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

View on GitHub (pinned to 52c9bd7908)