gohugoio/hugo · error

template %q not found

Error message

template %q not found

What it means

Returned by pageContentOutput.Render when resolveTemplate finds no template matching the requested layout name for the page's type, kind, and output format. The `.Render "name"` template call requires a corresponding layout file (e.g. layouts/summary.html or layouts/<section>/summary.html); if lookup succeeds with no error but no match, Hugo reports the first requested layout name as not found.

Source

Thrown at hugolib/page__per_output.go:117

	if pco == nil {
		return
	}
	pco.contentRenderedVersion++
	pco.contentRendered.Store(false)
	pco.renderHooks = &renderHooks{}
}

func (pco *pageContentOutput) Render(ctx context.Context, layout ...string) (template.HTML, error) {
	if len(layout) == 0 {
		return "", errors.New("no layout given")
	}
	templ, found, err := pco.po.p.resolveTemplate(layout...)
	if err != nil {
		return "", pco.po.p.wrapError(err)
	}

	if !found {
		return "", fmt.Errorf("template %q not found", layout[0])
	}

	// Make sure to send the *pageState and not the *pageContentOutput to the template.
	res, err := executeToString(ctx, pco.po.p.s.GetTemplateStore(), templ, pco.po.p)
	if err != nil {
		return "", pco.po.p.wrapError(fmt.Errorf("failed to execute template %s: %w", templ.Name(), err))
	}
	return template.HTML(res), nil
}

func (pco *pageContentOutput) Fragments(ctx context.Context) *tableofcontents.Fragments {
	return pco.c().Fragments(ctx)
}

func (pco *pageContentOutput) RenderShortcodes(ctx context.Context) (template.HTML, error) {
	return pco.c().RenderShortcodes(ctx)
}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Create the layout file the name refers to, e.g. layouts/summary.html (or layouts/<type>/summary.html), using the current Hugo layout conventions.
2. Check the theme/module is actually enabled (theme setting or module imports) so its layouts are on the lookup path.
3. Verify the name passed to .Render matches the file name exactly, and that a variant exists for the page's output format.
4. Run `hugo --printPathWarnings` / check `hugo config mounts` to confirm layouts are mounted where expected.

Example fix

<!-- template calls {{ .Render "li" }} -->
<!-- fix: add layouts/li.html -->
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>

{{/* In templates, guard explicit template lookups */}}
{{ with .Page.Layout }}{{ if not (templates.Exists (printf "layouts/%s.html" .)) }}{{ errorf "layout %q missing" . }}{{ end }}{{ end }}

When it happens

Trigger: `{{ .Render "summary" }}` when no summary.html exists anywhere in the layout lookup chain (project layouts, theme, module mounts) for that page's section/type/output format.

Common situations: Theme not installed or module not mounted so its layouts are missing, typo in the layout name, layout placed under an old path the current lookup rules no longer honor (e.g. layouts/_default/ in configs targeting the new layout system), or rendering to a non-HTML output format lacking that layout.

Related errors

• partial %q not found
• no layout given
• error building site: %w
• failed to detect format from content
• failed to detect target data serialization format

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