{"id":"a7cd5093bf042b67","repo":"gohugoio/hugo","slug":"failed-to-resolve-q-to-an-archetype-template","errorCode":null,"errorMessage":"failed to resolve %q to an archetype template","messagePattern":"failed to resolve %q to an archetype template","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"create/content.go","lineNumber":97,"sourceCode":"\text := paths.Ext(targetPath)\n\n\tb.setArcheTypeFilenameToUse(ext)\n\n\twithBuildLock := func() (string, error) {\n\t\tif !h.Configs.Base.NoBuildLock {\n\t\t\tunlock, err := h.BaseFs.LockBuild()\n\t\t\tif err != nil {\n\t\t\t\treturn \"\", fmt.Errorf(\"failed to acquire a build lock: %s\", err)\n\t\t\t}\n\t\t\tdefer unlock()\n\t\t}\n\n\t\tif b.isDir {\n\t\t\treturn \"\", b.buildDir()\n\t\t}\n\n\t\tif ext == \"\" {\n\t\t\treturn \"\", fmt.Errorf(\"failed to resolve %q to an archetype template\", targetPath)\n\t\t}\n\n\t\tif !h.Conf.ContentTypes().IsContentFile(b.targetPath) {\n\t\t\treturn \"\", fmt.Errorf(\"target path %q is not a known content format\", b.targetPath)\n\t\t}\n\n\t\treturn b.buildFile()\n\t}\n\n\tfilename, err := withBuildLock()\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif filename != \"\" {\n\t\treturn b.openInEditorIfConfigured(filename)\n\t}\n","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/create/content.go#L79-L115","documentation":"In create.NewContent, after resolving the archetype to use, a non-directory archetype requires the target path to carry a file extension (the extension selects which archetype file, e.g. default.md, applies). If paths.Ext(targetPath) is empty and no directory archetype matched, Hugo cannot pick an archetype template and fails.","triggerScenarios":"`hugo new content <path>` where <path> has no file extension (e.g. `hugo new posts/my-post`) and neither `archetypes/<kind>` nor `archetypes/default` exists as a directory — so setArcheTypeFilenameToUse found no directory archetype and the file path lacks the extension needed to match `<kind><ext>` or `default<ext>`.","commonSituations":"Forgetting the `.md` suffix when creating a page; expecting bundle creation (`hugo new posts/my-bundle`) without having a directory-style archetype for that section; typo in the `--kind` value so the intended directory archetype isn't found.","solutions":["Add an extension to the target path: `hugo new content posts/my-post.md`.","If you intended a leaf-bundle archetype, create a directory archetype (e.g. archetypes/posts/ containing index.md) so extension-less targets resolve to it.","Verify the `--kind`/section name matches an existing archetype directory name."],"exampleFix":"# before\nhugo new content posts/my-post\n# Error: failed to resolve \"posts/my-post\" to an archetype template\n\n# after\nhugo new content posts/my-post.md","handlingStrategy":"validation","validationCode":"kind := \"post\"\nif _, err := os.Stat(filepath.Join(\"archetypes\", kind+\".md\")); os.IsNotExist(err) {\n    kind = \"default\" // ensure archetypes/default.md exists\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep an archetypes/default.md as the universal fallback","Match --kind values to actual archetype file names (including theme archetypes)","Check the theme's archetypes directory when relying on theme templates"],"tags":["hugo","archetype","cli","content"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}