gohugoio/hugo · error

failed to execute archetype template: %s: %w

Error message

failed to execute archetype template: %s: %w

What it means

Returned by ContentFactory.ApplyArchetypeTemplate in hugolib/content_factory.go when executing the archetype template (used by `hugo new content`) fails at runtime. The archetype file parsed successfully as a Go template, but execution against the archetypeFileData context ({{ .Type }}, {{ .Date }}, {{ .Page }}, {{ .File }}) failed — typically a call to an undefined variable, a nil field, or a failing template function.

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 8a468df065)

Solutions

1. Read the wrapped error text after the message — it names the failing template action and line in the archetype.
2. Open the matching archetypes/<kind>.md (or the theme's archetype) and fix or guard the failing action, e.g. `{{ with .File }}{{ .ContentBaseName }}{{ end }}`.
3. Test the archetype with a minimal `hugo new content` invocation to confirm the fix.
4. If the archetype comes from a theme, override it by copying it into your project's archetypes/ directory and correcting it there.

Example fix

<!-- archetypes/post.md before -->
title: "{{ .File.ContentBaseName | title }}"
<!-- after: guard nil File -->
title: "{{ with .File }}{{ .ContentBaseName | title }}{{ else }}{{ .Type }}{{ end }}"

// verify archetype template parses before use
if _, err := template.New("archetype").Parse(archetypeSource); err != nil {
    return fmt.Errorf("invalid archetype: %w", err)
}

if err := cf.ApplyArchetypeFilename(w, p, kind, archetypeFilename); err != nil {
    if strings.Contains(err.Error(), "failed to execute archetype template") {
        // report template + underlying cause; do not create the content file
        log.Printf("archetype %q failed: %v", archetypeFilename, err)
    }
    return err
}

When it happens

Trigger: Running `hugo new content <path>` (or `hugo new`) with an archetype in archetypes/ whose template body errors during execution: e.g. calling a method on a nil .File, using site functions unavailable in the archetype context, or a template function like `errorf`/`time` failing on bad input. Also hit via the ContentFactory API when embedding Hugo.

Common situations: Copying archetype snippets from themes that assume fields not present for the new content kind; using .Site or page methods that aren't populated at archetype time; date/time formatting with an invalid layout; upgrading Hugo where a template function's behavior changed and the archetype now errors.

Related errors

• error building site: %w
• failed to resolve %q to an archetype template
• failed to open non-content file: %w
• failed to walk archetype dir %q: %w
• failed to read archetype file: %w

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