gohugoio/hugo · error

alias "" is an empty string

Error message

alias "" is an empty string

What it means

Returned by targetPathAlias (hugolib/alias.go:126) when an alias source path is the empty string. An empty alias cannot be turned into an output file path, so Hugo rejects it before cleaning and validating the path (a "/" alias is separately rejected as resolving to the site root).

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 8a468df065)

Solutions

1. Find the offending page and remove the empty entry from its aliases list.
2. Search content for empty alias entries: grep -rn 'aliases' content/ and check for blank items.
3. If aliases are generated by tooling or archetypes, skip emitting the field when the source value is empty.

Example fix

# before (front matter)
aliases:
  - ""
  - /old-url/
# after
aliases:
  - /old-url/

for _, a := range page.Aliases {
    if strings.TrimSpace(a) == "" {
        return fmt.Errorf("page %s: empty alias", page.Path())
    }
}

When it happens

Trigger: A page whose front matter aliases list contains an empty entry — aliases: [""] or a YAML list item left blank — passed into publishDestAlias during rendering.

Common situations: Archetype templates with a placeholder aliases field left empty, trailing commas or blank list items in YAML/TOML front matter, or scripts that generate aliases from a field that is sometimes empty (e.g. an old-URL field missing on some pages).

Related errors

• empty path is reserved for the home page
• error processing file %q
• failed to parse file %q: %s
• failed to convert metadata for file %q: %s
• redirects must have either From or FromRe set

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