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

Open the named archetype and locate the parse error line/column from the wrapped error.

failed to parse archetype template

Error message

failed to parse archetype template: %s: %w

What it means

Returned by ApplyArchetypeTemplate when TemplateStore.TextParse fails parsing the archetype source as a Go text/template. The archetype body (with shortcodes placeholder-swapped) had a syntax error: unbalanced delimiters, undefined function, bad pipeline, etc. The error is double-wrapped (%s and %w) for visibility.

Solutions

Open the named archetype and locate the parse error line/column from the wrapped error.
Balance all {{ }} delimiters and ensure every function used is registered in Hugo's template funcMap.
Test the archetype in isolation with `hugo new --kind <name> test/x.md` after each edit.
Run with --templateMetricsHints or a Go template linter to catch undefined functions.

Example fix

<!-- archetypes/post.md -->
<!-- before -->
+++
title = "{{ .Title"
+++
<!-- after -->
+++
title = "{{ .Title }}"
+++

Defensive patterns

Strategy: try-catch

Validate before calling

if _, err := template.New("t").Parse(archetypeSource); err != nil { /* parse error — fix before Hugo uses it */ }

Try / catch

if err := cf.ApplyArchetypeTemplate(w, p, kind, src); err != nil {
    if strings.Contains(err.Error(), "failed to parse archetype template") {
        // show the inner parse error to locate the syntax problem
    }
}

Prevention

Parse archetypes with text/template in a lint step before committing.
Balance all delimiters; only use Hugo-registered functions.
Re-test `hugo new` after every archetype edit.

When it happens

Trigger: An archetype file contains invalid Go template syntax — e.g. {{ .Title (missing close), {{ foo }}, a function that is not registered, mismatched {{/* */}}, or a shortcode placeholder left malformed. Triggered when `hugo new` applies the archetype.

Common situations: Editing an archetype and introducing a typo; upgrading Hugo so a previously-tolerated construct now errors; using a template func only available in a newer/different Hugo; copying a layout snippet into an archetype that references layout-only context.

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

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

Appendix: 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 52c9bd7908)