What causes "failed to parse archetype template: %s: %w" in gohugoio/hugo?

Fix the template syntax at the position given in the parse error (unclosed action, unknown function, etc.).

failed to parse archetype template: %s: %w

Error message

failed to parse archetype template: %s: %w

What it means

Archetype files are parsed as Go text templates (after shortcodes are temporarily replaced with placeholders) so that fields like {{ .Date }} and {{ .File.ContentBaseName }} can be expanded when creating new content. If TemplateStore.TextParse fails, the archetype contains invalid Go template syntax and `hugo new` aborts.

Source

Thrown at hugolib/content_factory.go:77

// ApplyArchetypeTemplate templateSource to w as a template using the given Page p as the foundation for the data context.
func (f ContentFactory) ApplyArchetypeTemplate(w io.Writer, p page.Page, archetypeKind, templateSource string) error {
	ps := p.(*pageState)
	if archetypeKind == "" {
		archetypeKind = p.Type()
	}

	d := &archetypeFileData{
		Type: archetypeKind,
		Date: htime.Now().Format(time.RFC3339),
		Page: p,
		File: p.File(),
	}

	templateSource = f.shortcodeReplacerPre.Replace(templateSource)

	templ, err := ps.s.TemplateStore.TextParse("archetype.md", templateSource)
	if err != nil {
		return fmt.Errorf("failed to parse archetype template: %s: %w", err, err)
	}

	result, err := executeToString(context.Background(), ps.s.GetTemplateStore(), templ, d)
	if err != nil {
		return fmt.Errorf("failed to execute archetype template: %s: %w", err, err)
	}

	_, err = io.WriteString(w, f.shortcodeReplacerPost.Replace(result))

	return err
}

func (f ContentFactory) SectionFromFilename(filename string) (string, error) {
	filename = filepath.Clean(filename)
	rel, _, err := f.h.AbsProjectContentDir(filename)
	if err != nil {
		return "", err
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Fix the template syntax at the position given in the parse error (unclosed action, unknown function, etc.).
Escape literal braces intended as text: use `{{ "{{" }}` or wrap example code so it isn't parsed.
Note shortcodes (`{{< ... >}}`/`{{% ... %}}`) are safe — they're placeholder-replaced — but plain `{{ ... }}` must be valid Go template code.
Temporarily simplify the archetype to isolate the offending line.

Example fix

<!-- before: archetypes/posts.md -->
---
title: "{{ replace .File.ContentBaseName "-" " " | title }"
---
<!-- after -->
---
title: "{{ replace .File.ContentBaseName "-" " " | title }}"
---

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-parse archetype templates in CI to catch syntax errors
b, _ := os.ReadFile(archetype)
if _, err := template.New("a").Funcs(funcMap).Parse(string(b)); err != nil {
    return fmt.Errorf("bad archetype template %s: %w", archetype, err)
}

Try / catch

if err := create.NewContent(h, kind, target); err != nil {
    if strings.Contains(err.Error(), "failed to parse archetype template") {
        // fix Go template syntax in the archetype (unclosed {{ }}, unknown function)
    }
    return err
}

Prevention

Archetypes are Go templates — balance every `{{` with `}}` and only use functions available in the archetype context (.Name, .Date, site, time, etc.)
Escape literal `{{` in example content with `{{"{{"}}` or template comments
Run `hugo new test-content.md` in CI whenever archetypes change to catch parse errors before users hit them

When it happens

Trigger: `hugo new content <path>` with an archetype containing malformed template actions — unclosed `{{`, unknown functions, bad pipeline syntax, or literal `{{` sequences (e.g. example code in the archetype body) that aren't escaped.

Common situations: Archetypes documenting template snippets that get interpreted, copy-pasted front matter with unbalanced braces, using functions unavailable in the archetype context, or Jinja/Liquid syntax from other generators pasted into a Hugo archetype.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/3cceeefa5d064b10.json. Report an issue: GitHub ↗.