gohugoio/hugo · error

no alias template found

Error message

no alias template found

What it means

renderAlias looks up the alias HTML layout (output.AliasHTMLFormat) via the template store. If no matching alias template is found in any resolved layout location, it errors. Hugo ships a built-in default alias template, so in practice this indicates the template system was unable to resolve it — e.g. an unusual layout/output-format configuration or a descriptor that does not match the alias template.

Solutions

1. Ensure the built-in alias template is available (avoid deleting/overriding layouts that supply alias.html).
2. Check that HTML output format is enabled for the relevant pages.
3. Review custom layout/outputFormat settings that change the descriptor used to look up the alias template.

// Ensure HTML output and an alias template are available before relying on aliases
if !outputFormatEnabled("HTML") {
    return errors.New("HTML output format must be enabled for aliases")
}

When it happens

Trigger: A page that emits aliases while the alias layout cannot be resolved because of custom layout overrides, disabled HTML output format, or a template descriptor mismatch.

Common situations: Overriding layouts in a way that removes the default alias template; disabling or misconfiguring the HTML output format for aliased pages; theme/layouts conflicts that hide the alias template.

Related errors

• argument must be a slice
• arguments must be slices or arrays
• arguments to complement must be slices or arrays
• arguments to symdiff must be slices or arrays
• both count and seq must be provided

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

Appendix: 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 52c9bd7908)