{"id":"e5aaf6d571188963","repo":"gohugoio/hugo","slug":"templates-defer-cannot-be-used-inside-a-partialcac","errorCode":null,"errorMessage":"templates.Defer cannot be used inside a partialCached partial; use partial instead, or move templates.Defer to the calling template","messagePattern":"templates\\.Defer cannot be used inside a partialCached partial; use partial instead, or move templates\\.Defer to the calling template","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tpl/templates/templates.go","lineNumber":65,"sourceCode":"\n// Exists returns whether the template with the given name exists.\n// Note that this is the Unix-styled relative path including filename suffix,\n// e.g. partials/header.html\nfunc (ns *Namespace) Exists(name string) bool {\n\treturn ns.deps.GetTemplateStore().HasTemplate(name)\n}\n\n// Defer defers the execution of a template block.\nfunc (ns *Namespace) Defer(ctx context.Context, args ...any) (bool, error) {\n\t// Prevent defer from being used in content adapters,\n\t// that just doesn't work.\n\tns.deps.Site.CheckReady()\n\n\t// Reject use inside a partialCached body: the cached output retains the\n\t// deferred placeholder across rebuilds while the executions map is reset,\n\t// which used to cause a panic in executeDeferredTemplates. See issue #13492.\n\tif tpl.Context.IsInPartialCached.Get(ctx) {\n\t\treturn false, fmt.Errorf(\"templates.Defer cannot be used inside a partialCached partial; use partial instead, or move templates.Defer to the calling template\")\n\t}\n\n\tif len(args) != 0 {\n\t\treturn false, fmt.Errorf(\"Defer does not take any arguments\")\n\t}\n\treturn true, nil\n}\n\nvar defferedIDCounter atomic.Uint64\n\ntype DeferOpts struct {\n\t// Optional cache key. If set, the deferred block will be executed\n\t// once per unique key.\n\tKey string\n\n\t// Optional data context to use when executing the deferred block.\n\tData any\n}","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/tpl/templates/templates.go#L47-L83","documentation":"`templates.Defer` postpones rendering of a block until after the site build (used e.g. for TailwindCSS class collection). Its output placeholder is incompatible with `partialCached`: the cached partial output would retain the deferred placeholder across rebuilds while the deferred-executions map is reset, which previously caused a panic in executeDeferredTemplates (see issue #13492). Hugo now detects the combination via the `IsInPartialCached` context flag and fails with this explicit error (tpl/templates/templates.go:64-66).","triggerScenarios":"A template calls `{{ partialCached \"foo.html\" . }}` and inside foo.html (or any partial it includes) there is a `{{ with (templates.Defer ...) }}` block. Triggers on server rebuilds and regular builds alike once the guard runs.","commonSituations":"Wrapping a site head/footer partial that contains the TailwindCSS `templates.Defer` snippet in partialCached for performance; themes updated to use templates.Defer while the site wraps theme partials in partialCached; upgrading Hugo past the version that added this guard turns a previously panicking or silently broken setup into this error.","solutions":["Change the `partialCached` call that includes the deferred block to a plain `partial` call.","Alternatively, move the `templates.Defer` block out of the cached partial and into the calling template (e.g. baseof.html), keeping the rest of the partial cached.","If the deferred work itself is expensive, use `templates.Defer (dict \"key\" ...)` — Defer has its own per-key caching, so partialCached is unnecessary around it."],"exampleFix":"<!-- before: layouts/baseof.html -->\n{{ partialCached \"css.html\" . }}\n<!-- partials/css.html contains {{ with (templates.Defer (dict \"key\" \"css\")) }}...{{ end }} -->\n\n<!-- after -->\n{{ partial \"css.html\" . }}\n<!-- or move the templates.Defer block directly into baseof.html -->","handlingStrategy":"validation","validationCode":"{{/* structural rule, checked at authoring time: */}}\n{{/* BAD:  {{ partialCached \"head.html\" . }} where head.html uses templates.Defer */}}\n{{/* GOOD: use {{ partial \"head.html\" . }} or hoist templates.Defer to the caller */}}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never place templates.Defer inside a partial invoked via partialCached — the deferred block would be cached and skipped","Switch that call site to plain partial, or move the templates.Defer block up into the calling template","Grep your theme for `templates.Defer` when adding partialCached wrappers"],"tags":["hugo","templates","partial-cached","defer","caching"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}