{"id":"5bd6ad05b8370e97","repo":"gohugoio/hugo","slug":"no-alias-template-found","errorCode":null,"errorMessage":"no alias template found","messagePattern":"no alias template found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/alias.go","lineNumber":70,"sourceCode":"\tvar base string = \"\"\n\tif ps, ok := p.(*pageState); ok {\n\t\tbase, templateDesc = ps.GetInternalTemplateBasePathAndDescriptor()\n\t}\n\ttemplateDesc.LayoutFromUser = \"\"\n\ttemplateDesc.Kind = \"\"\n\ttemplateDesc.OutputFormat = output.AliasHTMLFormat.Name\n\ttemplateDesc.MediaType = output.AliasHTMLFormat.MediaType.Type\n\n\tq := tplimpl.TemplateQuery{\n\t\tPath: base,\n\t\tCategory: tplimpl.CategoryLayout,\n\t\tDesc: templateDesc,\n\t\tSites: matrix,\n\t}\n\n\tt := a.ts.LookupPagesLayout(q)\n\tif t == nil {\n\t\treturn nil, errors.New(\"no alias template found\")\n\t}\n\n\tif p == nil {\n\t\tp = page.NopPage\n\t}\n\n\tdata := aliasPage{\n\t\tpermalink,\n\t\tp,\n\t}\n\n\tctx := a.ts.PrepareTopLevelRenderCtx(context.Background(), p)\n\n\tbuffer := new(bytes.Buffer)\n\terr := a.ts.ExecuteWithContext(ctx, t, buffer, data)\n\tif err != nil {\n\t\treturn nil, err\n\t}","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/alias.go#L52-L88","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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."],"exampleFix":"\n\n\n\n {{ .Permalink }}\n \n \n\n","handlingStrategy":"fallback","validationCode":"// before enabling aliases with a custom alias template, confirm it exists:\nif _, err := os.Stat(\"layouts/alias.html\"); os.IsNotExist(err) {\n // rely on Hugo's embedded default alias template instead\n}","typeGuard":null,"tryCatchPattern":"if err := site.Build(...); err != nil {\n if strings.Contains(err.Error(), \"no alias template found\") {\n // template lookup misconfigured; restore layouts/alias.html or remove the override\n }\n return err\n}","preventionTips":["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"],"tags":["hugo","alias","template","layout"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}