{"record":{"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/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/tpl/tplimpl/templatetransform.go#L70-L106","documentation":"applyTemplateTransformers (templatetransform.go:71-91) runs an AST transformation pass over each parsed template to inject partial-return wrappers, deferred nodes, and partial-decorator handling. If applyTransformationsAndSetReturnWrapper returns an error, it is wrapped with the template name. This is a build-time parse/transform failure on a specific template.","triggerScenarios":"A template whose parsed AST cannot be transformed — typically because a nested transformation (config decode, partial decorator creation, inner-insertion) failed. The wrapped error identifies the specific sub-failure; the outer message identifies which template it happened in.","commonSituations":"A malformed $_hugo_config header; a {{ with }} block wrapping a partial decorator that contains an unsupported construct; syntax that parses but is semantically invalid during the transform pass; Hugo version regression in the transformer.","solutions":["Read the wrapped (%w) error to find the specific transformation that failed.","Inspect the named template for unsupported constructs (e.g. {{ inner }} inside a with-partial, bad $_hugo_config).","Simplify the template to isolate which construct triggers the transform failure.","Update Hugo; transform logic is frequently patched."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// In Go tests/builds, unwrap to find the specific sub-transform failure:\nif err != nil && strings.Contains(err.Error(), \"failed to transform template\") {\n    // the %w holds the real cause (e.g. $_hugo_config decode, inner-in-with)\n    log.Fatalf(\"transform failed for template: %v\", err)\n}","preventionTips":["Always inspect the wrapped cause, not just the outer template name.","Validate $_hugo_config and avoid 'inner' inside with-partial blocks.","Simplify templates when diagnosing transform errors."],"tags":["template","transform","build","ast","parse-error"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}