gohugoio/hugo · error

archetype directory ( ) not supported

Error message

archetype directory (%q) not supported

What it means

Returned by ContentFactory.ApplyArchetypeFi when the supplied FileMetaInfo fi.IsDir() is true. Archetype application expects a single template file to parse and execute; a directory (an archetype bundle/folder) is not handled by this code path and is rejected with the directory's Meta().Filename.

Solutions

1. Point the archetype argument at a file inside the directory (e.g. archetypes/myarchetype/index.md) or a top-level archetype file.
2. Create the expected single archetype file (archetypes/<name>.md) if missing.
3. If using `hugo new section/page.md`, ensure archetypes/<section>.md exists as a file, not a directory.

Example fix

# before
$ hugo new posts/hello.md --kind posts
# archetypes/posts/  (directory)
# after
# archetypes/posts.md  (single file)

func resolveArchetypeFile(root, name string) (hugofs.FileMetaInfo, error) {
    fi, err := fs.Stat(filepath.Join(root, name))
    if err != nil { return nil, err }
    if fi.IsDir() { return nil, fmt.Errorf("archetype is a directory; need a file") }
    return fi, nil
}

func isArchetypeFile(fi hugofs.FileMetaInfo) bool { return !fi.IsDir() }

When it happens

Trigger: Calling ApplyArchetypeFi with a hugofs.FileMetaInfo that points at a directory — e.g. the resolved archetype path resolved to a folder like archetypes/default/ rather than archetypes/default.md. Internally this backs `hugo new` archetype scaffolding.

Common situations: An archetype folder exists with the requested name but no matching file; a user/CI calls the content-creation API with a path that lands on a directory; migration from a bundle-style archetype setup to single-file archetypes.

Related errors

• failed to execute archetype template
• failed to parse archetype template
• failed to read archetype file
• failed to open non-content file
• failed to read archetype file

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

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