gohugoio/hugo · error

http* aliases not supported

Error message

http* aliases not supported: %q

What it means

Companion validation to 357, applied to `aliases` (page__meta.go:762). Each alias is iterated and must be path-relative; any alias beginning with http:// or https:// is rejected because aliases become redirect routes on this site and an absolute URL is invalid for that purpose.

Solutions

1. Make aliases path-relative: `aliases: [/old/path/, /another/]`.
2. Keep absolute-URL redirects outside Hugo aliases (web server / redirect service).
3. Strip scheme+host from each alias value.

Example fix

// before
---
aliases:
  - https://old.com/about/
---

// after
---
aliases:
  - /about/
---

# every alias must be path-relative
for a in "${aliases[@]}"; do case "$a" in http://*|https://*) echo "bad alias: $a";; esac; done

When it happens

Trigger: Front matter lists an absolute URL among aliases, e.g. `aliases: [https://old.com/page]`. The loop checks each entry's prefix and fails the build on the first offending alias.

Common situations: Treating aliases like canonical external redirects; copying old-site absolute URLs into aliases during migration.

Related errors

• URLs with protocol (http*) not supported
• alias "" is an empty string
• failed to create page from file
• failed to create page meta from file
• no taxonomy configuration found for

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

Appendix: source

Thrown at hugolib/page__meta.go:762

			// lower case names:
			for i, s := range o {
				o[i] = strings.ToLower(s)
			}
			pm.pageConfig.Outputs = o
		case "draft":
			draft = new(bool)
			*draft = cast.ToBool(v)
		case "layout":
			pcfg.Layout = cast.ToString(v)
			pcfg.Params[loki] = pcfg.Layout
		case "weight":
			pcfg.Weight = cast.ToInt(v)
			pcfg.Params[loki] = pcfg.Weight
		case "aliases":
			pcfg.Aliases = cast.ToStringSlice(v)
			for i, alias := range pcfg.Aliases {
				if strings.HasPrefix(alias, "http://") || strings.HasPrefix(alias, "https://") {
					return fmt.Errorf("http* aliases not supported: %q", alias)
				}
				pcfg.Aliases[i] = filepath.ToSlash(alias)
			}
			pcfg.Params[loki] = pcfg.Aliases
		case "sitemap":
			pcfg.Sitemap, err = config.DecodeSitemap(ps.s.conf.Sitemap, hmaps.ToStringMap(v))
			if err != nil {
				return fmt.Errorf("failed to decode sitemap config in front matter: %s", err)
			}
			sitemapSet = true
		case "iscjklanguage":
			isCJKLanguage = new(bool)
			*isCJKLanguage = cast.ToBool(v)
		case "translationkey":
			pcfg.TranslationKey = cast.ToString(v)
			pcfg.Params[loki] = pcfg.TranslationKey
		case "resources":
			var resources []map[string]any

View on GitHub (pinned to 52c9bd7908)