gohugoio/hugo · critical

template %q not found

Error message

template %q not found

What it means

Panic raised while executing a deferred template: the deferred entry references a TemplatePath, but LookupByPath on the template store returns nil. This means a template path recorded during the render pass is no longer resolvable at execution time. Like 781 it is an internal consistency error in Hugo's deferred-template lifecycle.

Source

Thrown at hugolib/hugo_sites_build.go:556

			low, high := k+l, k+l+m

			forward := l + m
			id := string(content[low:high])

			if err := func() error {
				deferred, found := de.Executions.Get(id)
				if !found {
					panic(fmt.Sprintf("deferred execution with id %q not found", id))
				}
				deferred.Mu.Lock()
				defer deferred.Mu.Unlock()

				if !deferred.Executed {
					tmpl := s.Deps.GetTemplateStore()
					ti := s.TemplateStore.LookupByPath(deferred.TemplatePath)
					if ti == nil {
						panic(fmt.Sprintf("template %q not found", deferred.TemplatePath))
					}

					if err := func() error {
						buf := bufferpool.GetBuffer()
						defer bufferpool.PutBuffer(buf)

						err = tmpl.ExecuteWithContext(deferred.Ctx, ti, buf, deferred.Data)
						if err != nil {
							return err
						}
						deferred.Result = buf.String()
						deferred.Executed = true

						return nil
					}(); err != nil {
						return err
					}
				}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Clean-rebuild to discard stale template references (clear public/ and the Hugo cache).
2. Verify the template/partial file at the path reported in the panic exists in layouts/ (or the theme) and has no typos.
3. Restart the hugo server / process to rebuild the template store fresh.
4. Upgrade Hugo; report the issue with the deferred TemplatePath if it reproduces on a clean build.

Example fix

// layouts/_default/_markup/render-link.html was renamed during live reload
# Fix: ensure the referenced template path exists, then rebuild
rm -rf public resources/_gen && hugo server --disableFastRender

// Validate that referenced partials/templates exist before building.
// In templates, prefer partial names that resolve at parse time.
// Before a build you can list loaded templates via the deps template store if embedding Hugo.

// Wrap Build to convert panics into errors (see 781). Not a substitute for fixing the missing template.

When it happens

Trigger: A deferred template/partial whose path was registered but whose template was removed, renamed, or not loaded into the TemplateStore used at resolution time. Reentering rendering after template changes without rebuilding the store. A baseof/override mismatch where the looked-up path does not exist.

Common situations: Editing or renaming a partial that participates in a deferred execution during a live reload/incremental build. Mismatched theme vs project template paths. Hugo version change altering how template paths are keyed. A layout referenced by a render hook that is missing from the working dir.

Related errors

• deferred execution with id %q not found
• must have deps
• resource %d to post process is nil
• nil deps on site
• error building site: %w

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