gohugoio/hugo · error

failed to parse Resource

Error message

failed to parse Resource %q as Template:: %w

What it means

Returned by the executeAsTemplateTransform when th.TextParse fails to parse the resource's content as a Go text/template. The resource content is read as a string and parsed with the template store's TextParse keyed by the resource's InPath; any template syntax error is wrapped here.

Solutions

1. Read the wrapped %w cause; it names the line/column of the template parse error inside the resource.
2. Fix the template syntax in the source asset, or escape literal braces where you did not intend a template action.
3. Ensure any function used in the template is a valid Hugo/template function name.

Example fix

// before (asset contains invalid action)
{ "title": "{{ .Title " }}

// after
{ "title": "{{ .Title }}" }

// Pre-parse asset as a Go template to surface errors before Hugo build.
import "text/template"
if _, err := template.New("asset").Parse(string(content)); err != nil {
    return fmt.Errorf("template parse error in %s: %w", path, err)
}

// Wrap ExecuteAsTemplate and report the wrapped parse error.
r, err := res.TransformWithContext(ctx, t)
if err != nil {
    var pErr *tplParse.Error // if exposed
    if errors.As(err, &pErr) { /* surface line/col */ }
    return nil, fmt.Errorf("execute-as-template failed: %w", err)
}

When it happens

Trigger: Calling resources.ExecuteAsTemplate (or css.ExecuteAsTemplate / the templates.ExecuteAsTemplate transformer) on a resource whose content contains invalid Go template syntax — unclosed actions, bad delimiters, undefined functions, or malformed pipelines.

Common situations: Using ExecuteAsTemplate on a CSS/JS/JSON file that contains '{{' or other template delimiters unintentionally, referencing a function not registered in Hugo's template namespace, or a stray '{{ end }}' / missing '{{ if }}'.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to decode $_hugo_config in template
• failed to parse empty HTML template
• failed to parse empty text template
• failed to transform template
• arg

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

Appendix: source

Thrown at resources/resource_transformers/templates/execute_as_template.go:62

}

type executeAsTemplateTransform struct {
	rs         *resources.Spec
	t          tplimpl.TemplateStoreProvider
	targetPath string
	data       any
}

func (t *executeAsTemplateTransform) Key() internal.ResourceTransformationKey {
	return internal.NewResourceTransformationKey("execute-as-template", t.targetPath)
}

func (t *executeAsTemplateTransform) Transform(ctx *resources.ResourceTransformationCtx) error {
	tplStr := helpers.ReaderToString(ctx.From)
	th := t.t.GetTemplateStore()
	ti, err := th.TextParse(ctx.InPath, tplStr)
	if err != nil {
		return fmt.Errorf("failed to parse Resource %q as Template:: %w", ctx.InPath, err)
	}
	ctx.OutPath = t.targetPath
	return th.ExecuteWithContext(ctx.Ctx, ti, ctx.To, t.data)
}

func (c *Client) ExecuteAsTemplate(ctx context.Context, res resources.ResourceTransformer, targetPath string, data any) (resource.Resource, error) {
	return res.TransformWithContext(ctx, &executeAsTemplateTransform{
		rs:         c.rs,
		targetPath: paths.ToSlashTrimLeading(targetPath),
		t:          c.t,
		data:       data,
	})
}

View on GitHub (pinned to 52c9bd7908)