What causes "no alias template found" in gohugoio/hugo?

Restore or fix your custom alias template at layouts/alias.html (or delete it to fall back to Hugo's embedded one).

no alias template found

Error message

no alias template found

What it means

Returned by the alias handler (hugolib/alias.go:70) when LookupPagesLayout finds no template to render an alias redirect page. Hugo renders each front-matter alias as a small HTML meta-refresh page using the alias template; normally the embedded built-in alias template guarantees a match, so a nil lookup means the template store's alias template was overridden away or the lookup matrix has no matching site/output.

Source

Thrown at hugolib/alias.go:70

	var base string = ""
	if ps, ok := p.(*pageState); ok {
		base, templateDesc = ps.GetInternalTemplateBasePathAndDescriptor()
	}
	templateDesc.LayoutFromUser = ""
	templateDesc.Kind = ""
	templateDesc.OutputFormat = output.AliasHTMLFormat.Name
	templateDesc.MediaType = output.AliasHTMLFormat.MediaType.Type

	q := tplimpl.TemplateQuery{
		Path:     base,
		Category: tplimpl.CategoryLayout,
		Desc:     templateDesc,
		Sites:    matrix,
	}

	t := a.ts.LookupPagesLayout(q)
	if t == nil {
		return nil, errors.New("no alias template found")
	}

	if p == nil {
		p = page.NopPage
	}

	data := aliasPage{
		permalink,
		p,
	}

	ctx := a.ts.PrepareTopLevelRenderCtx(context.Background(), p)

	buffer := new(bytes.Buffer)
	err := a.ts.ExecuteWithContext(ctx, t, buffer, data)
	if err != nil {
		return nil, err
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Restore or fix your custom alias template at layouts/alias.html (or delete it to fall back to Hugo's embedded one).
Check custom outputFormats/mediaTypes config for redefinitions of the HTML media type that could break the alias output format.
Reproduce with a stock theme/minimal config to confirm the override is the cause.
Alternatively set disableAliases = true and handle redirects at the server/CDN layer.

Example fix

<!-- restore layouts/alias.html -->
<!DOCTYPE html>
<html lang="en-us">
<head>
  <title>{{ .Permalink }}</title>
  <link rel="canonical" href="{{ .Permalink }}">
  <meta http-equiv="refresh" content="0; url={{ .Permalink }}">
</head>
</html>

Defensive patterns

Strategy: fallback

Validate before calling

// before enabling aliases with a custom alias template, confirm it exists:
if _, err := os.Stat("layouts/alias.html"); os.IsNotExist(err) {
    // rely on Hugo's embedded default alias template instead
}

Try / catch

if err := site.Build(...); err != nil {
    if strings.Contains(err.Error(), "no alias template found") {
        // template lookup misconfigured; restore layouts/alias.html or remove the override
    }
    return err
}

Prevention

If you override the alias template, keep layouts/alias.html present and parseable
Don't disable or shadow Hugo's embedded templates unless you supply replacements
When theme-switching, verify aliases still render by building a page that declares an alias

When it happens

Trigger: Publishing a page with aliases in front matter when the alias template lookup (Category layout, AliasHTMLFormat output) resolves to nothing — e.g. a project/theme layouts/alias.html that shadowed the embedded one was removed while the store cached state, or a broken custom output-format/template setup that excludes the alias HTML format.

Common situations: Themes overriding alias.html incorrectly, custom outputFormats/mediaTypes config that redefines HTML in a way the alias format can't match, or heavily customized template roots missing Hugo's embedded templates (unusual in stock setups).

Related errors

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