gohugoio/hugo · error

failed to execute archetype template

Error message

failed to execute archetype template: %s: %w

What it means

Returned by ApplyArchetypeTemplate when executeToString fails executing the parsed archetype template against the archetypeFileData context (Type, Date, Page, File). The template parsed fine but evaluation panicked/errored: nil-pointer deref on a missing field, a function returning an error, range over non-iterable, etc.

Solutions

1. Read the wrapped execution error for the template line and offending expression.
2. Guard nil-prone accesses: {{ with .File }}{{ .Path }}{{ end }} instead of {{ .File.Path }}.
3. Verify every template function signature against the Hugo docs for your version.
4. Simplify the archetype to a known-good baseline and re-add logic incrementally to isolate the failing call.

Example fix

<!-- archetypes/post.md -->
<!-- before -->
slug: "{{ .File.Dir }}{{ .File.BaseFileName }}"
<!-- after -->
slug: "{{ with .File }}{{ .Dir }}{{ .BaseFileName }}{{ end }}"

tmpl, _ := template.New("t").Parse(src)
var buf bytes.Buffer
if err := tmpl.Execute(&buf, data); err != nil { /* execution problem — guard nil fields */ }

if err := cf.ApplyArchetypeTemplate(w, p, kind, src); err != nil {
    if strings.Contains(err.Error(), "failed to execute archetype template") {
        // inspect wrapped error for the offending expression/field
    }
}

When it happens

Trigger: Archetype references a field/method that is nil for the new page at creation time (e.g. .File on a section-only context), calls a template function with wrong arg types, or ranges over something non-iterable. The shortcode placeholder replacer runs only after, so errors are from the user template logic.

Common situations: Archetype using .Params.<x> or .File.<y> that doesn't exist on a fresh page; switching archetypeKind; Hugo version change altering the page context shape; archetype calling a partial that errors.

Related errors

• failed to parse archetype template
• archetype directory ( ) not supported
• failed to read archetype file
• alias "" is an empty string
• alias " " resolves to website root directory

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

Appendix: source

Thrown at hugolib/content_factory.go:82

	}

	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
	}

	parts := strings.Split(paths.ToSlashTrimLeading(rel), "/")
	if len(parts) < 2 {
		return "", nil
	}

View on GitHub (pinned to 52c9bd7908)