{"record":{"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":"validation","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/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/hugolib/content_factory.go#L30-L66","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Point the archetype argument at a file inside the directory (e.g. archetypes/myarchetype/index.md) or a top-level archetype file.","Create the expected single archetype file (archetypes/<name>.md) if missing.","If using `hugo new section/page.md`, ensure archetypes/<section>.md exists as a file, not a directory."],"exampleFix":"# before\n$ hugo new posts/hello.md --kind posts\n# archetypes/posts/  (directory)\n# after\n# archetypes/posts.md  (single file)","handlingStrategy":"validation","validationCode":"func resolveArchetypeFile(root, name string) (hugofs.FileMetaInfo, error) {\n    fi, err := fs.Stat(filepath.Join(root, name))\n    if err != nil { return nil, err }\n    if fi.IsDir() { return nil, fmt.Errorf(\"archetype is a directory; need a file\") }\n    return fi, nil\n}","typeGuard":"func isArchetypeFile(fi hugofs.FileMetaInfo) bool { return !fi.IsDir() }","tryCatchPattern":null,"preventionTips":["Ensure archetypes/<kind>.md exists as a file before `hugo new --kind <kind>`.","Type-guard against directories before calling ApplyArchetypeFi.","Keep archetypes as single files, not folders, unless the API supports folders."],"tags":["archetype","content-factory","hugolib","filesystem"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}