What causes "archetype directory (%q) not supported" in gohugoio/hugo?

Use a file archetype (e.g. `archetypes/posts.md`) for single-file content, or a proper bundle archetype directory containing an index.md, which Hugo's `new content` command handles via the bundle path.

gohugoio/hugo · error

archetype directory (%q) not supported

Error message

archetype directory (%q) not supported

What it means

ContentFactory.ApplyArchetypeFi applies a single archetype file as a Go template when creating new content; it explicitly rejects a directory FileMetaInfo. Directory-based archetypes (bundle archetypes) are handled by a different code path, so reaching this function with a directory indicates the archetype resolution picked something this API cannot process.

Source

Thrown at hugolib/content_factory.go:48

	"github.com/gohugoio/hugo/resources/page"

	"github.com/spf13/afero"
)

// ContentFactory creates content files from archetype templates.
type ContentFactory struct {
	h *HugoSites

	// We parse the archetype templates as Go templates, so we need
	// to replace any shortcode with a temporary placeholder.
	shortcodeReplacerPre  *strings.Replacer
	shortcodeReplacerPost *strings.Replacer
}

// ApplyArchetypeFilename archetypeFilename to w as a template using the given Page p as the foundation for the data context.
func (f ContentFactory) ApplyArchetypeFi(w io.Writer, p page.Page, archetypeKind string, fi hugofs.FileMetaInfo) error {
	if fi.IsDir() {
		return fmt.Errorf("archetype directory (%q) not supported", fi.Meta().Filename)
	}

	templateSource, err := fi.Meta().ReadAll()
	if err != nil {
		return fmt.Errorf("failed to read archetype file %q: %s: %w", fi.Meta().Filename, err, err)
	}

	return f.ApplyArchetypeTemplate(w, p, archetypeKind, string(templateSource))
}

// 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{

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Use a file archetype (e.g. `archetypes/posts.md`) for single-file content, or a proper bundle archetype directory containing an index.md, which Hugo's `new content` command handles via the bundle path.
Check the printed path and remove/rename the conflicting directory in archetypes/.
Run `hugo new content section/name/index.md` to create bundle content so the bundle-archetype flow is used.

Defensive patterns

Strategy: validation

Validate before calling

// Before `hugo new` with a directory archetype, verify it contains index.md
if fi, _ := os.Stat(archetypePath); fi != nil && fi.IsDir() {
    if _, err := os.Stat(filepath.Join(archetypePath, "index.md")); err != nil {
        return fmt.Errorf("archetype dir %q needs an index.md", archetypePath)
    }
}

Type guard

func validArchetypeDir(dir string) bool {
    _, err := os.Stat(filepath.Join(dir, "index.md"))
    return err == nil
}

Try / catch

if err := create.NewContent(h, kind, target); err != nil {
    if strings.Contains(err.Error(), "archetype directory") {
        // the directory archetype lacks index.md — add one, or use a single-file archetype
    }
    return err
}

Prevention

Directory (page-bundle) archetypes must contain an index.md at their root
For simple content, prefer single-file archetypes like archetypes/posts.md
Test each archetype with `hugo new` in CI after changing the archetypes directory

When it happens

Trigger: `hugo new content <path>` (or an API caller of ApplyArchetypeFi) resolves the archetype lookup to a directory entry rather than a template file — e.g. an archetype path that names a folder without going through the archetype-bundle handling.

Common situations: Archetype layouts where a folder exists with the same name expected for a file archetype (e.g. `archetypes/posts/` without the bundle flow), themes shipping unusual archetype structures, or custom tooling calling the API with a directory FileMetaInfo.

Related errors

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