What causes "deferred execution with id %q not found" in gohugoio/hugo?

Run a clean build (remove the Hugo project cache / resources/_gen and the build lock) to eliminate stale incremental state.

gohugoio/hugo · critical

deferred execution with id %q not found

Error message

deferred execution with id %q not found

What it means

Panic during post-publish content rewriting when a deferred-template marker found in rendered output has an ID that is absent from the de.Executions map. Hugo inserts deferred template fragments during rendering and resolves them after the main publish pass; an unknown ID means the bookkeeping that registers deferred executions drifted out of sync with the markers written into the content. The code comment around it implies this should never happen under normal operation, marking it an internal bug.

Source

Thrown at hugolib/hugo_sites_build.go:547

		for {
			if k >= len(content) {
				break
			}
			l := bytes.Index(content[k:], []byte(tpl.HugoDeferredTemplatePrefix))
			if l == -1 {
				break
			}
			m := bytes.Index(content[k+l:], []byte(tpl.HugoDeferredTemplateSuffix)) + len(tpl.HugoDeferredTemplateSuffix)

			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

View on GitHub (pinned to 52c9bd7908)

Solutions

Run a clean build (remove the Hugo project cache / resources/_gen and the build lock) to eliminate stale incremental state.
Update Hugo to the latest patch release; this is almost always an internal bookkeeping bug.
Identify the template using deferred execution and simplify it; file a Hugo issue with the template and the offending ID.
If you forked Hugo, audit concurrent access to the de.Executions map during the render+post-publish sequence.

Example fix

# before: incremental build hits the panic
hugo

# after: purge cache and rebuild
rm -rf public resources/_gen .hugo_build.lock && hugo --cleanDestinationDir

Defensive patterns

Strategy: validation

Validate before calling

// Not directly preventable by an API user — it is an internal invariant.
// Mitigate by running a clean build when incremental state is suspect:
//   rm -rf public resources/_gen .hugo_build.lock && hugo
// In embedded use, call Build with config.NoBuildLock=false only when state is fresh.

Try / catch

// Go panics can be recovered, but only do this to surface a friendly error:
func safeBuild(h *hugolib.HugoSites, cfg config.BuildCfg) (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("hugo build panicked: %v", r)
        }
    }()
    return h.Build(cfg)
}

Prevention

Clean the build cache when you see deferred-template panics.
Keep Hugo updated to pick up fixes to the deferred execution registry.
Avoid forking the deferred-template lifecycle.
If using custom output formats, test them against a clean build.

When it happens

Trigger: A template uses the Hugo deferred-template mechanism (deferred templates / partials evaluated late) and the registered Execution set is mutated or cleared between the render pass and the post-publish resolution pass. Concurrent/parallel rendering mutating the shared de.Executions map, or a custom output format that reorders the publish pipeline. Typically only seen with non-standard or partially-broken template constructs.

Common situations: Hugo version upgrade that changed the deferred-template protocol while stale incremental-build state lingers. A bug in a custom output format or render hook. A corrupted incremental build cache (run a clean build). A race in a fork that altered the deferred execution registry.

Related errors

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