gohugoio/hugo · error

http* aliases not supported: %q

Error message

http* aliases not supported: %q

What it means

The `aliases` front matter field creates redirect stub pages inside the site's publish directory, so each alias must be a site-relative path. Hugo rejects aliases starting with http:// or https:// because it cannot write a redirect page at an external domain.

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

Solutions

1. Use only the path portion: `aliases: ["/old-post/", "/2019/old-post/"]`.
2. For redirects from a different domain, configure them at the old domain's server/CDN (e.g. Netlify _redirects, nginx), not in Hugo aliases.

Example fix

# before
---
aliases:
  - https://example.com/old-url/
---
# after
---
aliases:
  - /old-url/
---

// Validate aliases before build
for _, a := range aliases {
    if strings.HasPrefix(strings.ToLower(a), "http") {
        return fmt.Errorf("alias %q must be relative", a)
    }
}

func validAlias(a string) bool {
    return !strings.HasPrefix(strings.ToLower(a), "http")
}

if err := site.Build(); err != nil {
    if strings.Contains(err.Error(), "aliases not supported") {
        // convert absolute alias URLs to site-relative paths
    }
    return err
}

When it happens

Trigger: Front matter contains `aliases: ["https://old.example.com/post"]` or any alias entry with an http(s) prefix; raised while decoding the aliases list during page metadata setup.

Common situations: Migrations from another domain where users paste full old URLs as aliases hoping for cross-domain redirects, or copying canonical URLs from a browser into the aliases list.

Related errors

• alias "%s" resolves to website root directory
• alias "%s" traverses outside the website root directory
• error processing file %q
• failed to parse file %q: %s
• failed to convert metadata for file %q: %s

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