{"id":"a7b97b2e2f2b1e2b","repo":"gohugoio/hugo","slug":"failed-to-transform-template-q-w","errorCode":null,"errorMessage":"failed to transform template %q: %w","messagePattern":"failed to transform template %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tpl/tplimpl/templatetransform.go","lineNumber":88,"sourceCode":"\nfunc applyTemplateTransformers(\n\tt *TemplInfo,\n\tstore *TemplateStore,\n\tlookupFn func(name string, in *TemplInfo) *TemplInfo,\n) (*templateTransformContext, error) {\n\tif t == nil {\n\t\treturn nil, errors.New(\"expected template, but none provided\")\n\t}\n\n\tc := newTemplateTransformContext(t, store, lookupFn)\n\tc.t.ParseInfo = defaultParseInfo\n\ttree := getParseTree(t.Template)\n\tif tree == nil {\n\t\tpanic(fmt.Errorf(\"template %s not parsed\", t))\n\t}\n\n\tif err := c.applyTransformationsAndSetReturnWrapper(tree); err != nil {\n\t\treturn c, fmt.Errorf(\"failed to transform template %q: %w\", t.Name(), err)\n\t}\n\n\treturn c, c.err\n}\n\nfunc getParseTree(templ tpl.Template) *parse.Tree {\n\tif text, ok := templ.(*texttemplate.Template); ok {\n\t\treturn text.Tree\n\t}\n\treturn templ.(*htmltemplate.Template).Tree\n}\n\nconst (\n\t// We parse this template and modify the nodes in order to assign\n\t// the return value of a partial to a contextWrapper via Set. We use\n\t// \"range\" over a one-element slice so we can shift dot to the\n\t// partial's argument, Arg, while allowing Arg to be falsy.\n\tpartialReturnWrapperTempl = `{{ $_hugo_dot := $ }}{{ $ := .Arg }}{{ range (slice .Arg) }}{{ $_hugo_dot.Set (\"PLACEHOLDER\") }}{{ end }}`","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/tpl/tplimpl/templatetransform.go#L70-L106","documentation":"Wrapper error returned when Hugo's template transformation pass fails for a specific template. After parsing, Hugo rewrites the parse tree (partial return-value wrapping, templates.Defer handling, partial decorators); any error from those transformations is wrapped with the template's name so the failing layout/partial is identifiable.","triggerScenarios":"applyTransformationsAndSetReturnWrapper returns an error for template %q — e.g. malformed use of templates.Defer, partial decorator constructs, or inner/with misuse detected during tree rewriting (see errors 152/153, which surface wrapped by this one).","commonSituations":"Appears at build time after editing a layout or partial that uses templates.Defer, {{ with (partial ...) }} decorator patterns, or block/inner constructs; also after upgrading Hugo when transformation rules tightened.","solutions":["Read the wrapped inner error — it names the actual rule violated — and fix that construct in the named template.","Open the template named in %q and review recent changes to Defer/partial/with usage.","Check the Hugo docs for templates.Defer and partial decorator constraints matching the inner error.","Re-run 'hugo' to confirm the template transforms cleanly."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"# Treat this as a build-time syntax failure: run\nhugo build --logLevel debug\n# and fix the template named in %q; the wrapped %w shows the parse/transform cause","preventionTips":["Read the wrapped inner error — it names the exact template construct that failed","Keep template edits small and build after each change so the failing template is obvious","Lint templates in CI so transform failures never reach deploy"],"tags":["hugo","templates","build"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}