{"id":"e146c2033f55e9a5","repo":"gohugoio/hugo","slug":"archetype-directory-q-not-supported","errorCode":null,"errorMessage":"archetype directory (%q) not supported","messagePattern":"archetype directory \\(%q\\) not supported","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/content_factory.go","lineNumber":48,"sourceCode":"\t\"github.com/gohugoio/hugo/resources/page\"\n\n\t\"github.com/spf13/afero\"\n)\n\n// ContentFactory creates content files from archetype templates.\ntype ContentFactory struct {\n\th *HugoSites\n\n\t// We parse the archetype templates as Go templates, so we need\n\t// to replace any shortcode with a temporary placeholder.\n\tshortcodeReplacerPre  *strings.Replacer\n\tshortcodeReplacerPost *strings.Replacer\n}\n\n// ApplyArchetypeFilename archetypeFilename to w as a template using the given Page p as the foundation for the data context.\nfunc (f ContentFactory) ApplyArchetypeFi(w io.Writer, p page.Page, archetypeKind string, fi hugofs.FileMetaInfo) error {\n\tif fi.IsDir() {\n\t\treturn fmt.Errorf(\"archetype directory (%q) not supported\", fi.Meta().Filename)\n\t}\n\n\ttemplateSource, err := fi.Meta().ReadAll()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to read archetype file %q: %s: %w\", fi.Meta().Filename, err, err)\n\t}\n\n\treturn f.ApplyArchetypeTemplate(w, p, archetypeKind, string(templateSource))\n}\n\n// ApplyArchetypeTemplate templateSource to w as a template using the given Page p as the foundation for the data context.\nfunc (f ContentFactory) ApplyArchetypeTemplate(w io.Writer, p page.Page, archetypeKind, templateSource string) error {\n\tps := p.(*pageState)\n\tif archetypeKind == \"\" {\n\t\tarchetypeKind = p.Type()\n\t}\n\n\td := &archetypeFileData{","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/content_factory.go#L30-L66","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Before `hugo new` with a directory archetype, verify it contains index.md\nif fi, _ := os.Stat(archetypePath); fi != nil && fi.IsDir() {\n    if _, err := os.Stat(filepath.Join(archetypePath, \"index.md\")); err != nil {\n        return fmt.Errorf(\"archetype dir %q needs an index.md\", archetypePath)\n    }\n}","typeGuard":"func validArchetypeDir(dir string) bool {\n    _, err := os.Stat(filepath.Join(dir, \"index.md\"))\n    return err == nil\n}","tryCatchPattern":"if err := create.NewContent(h, kind, target); err != nil {\n    if strings.Contains(err.Error(), \"archetype directory\") {\n        // the directory archetype lacks index.md — add one, or use a single-file archetype\n    }\n    return err\n}","preventionTips":["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"],"tags":["hugo","archetypes","content-creation","cli"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}