{"id":"6098930f21aea9ad","repo":"gohugoio/hugo","slug":"failed-to-read-archetype-file-q-s-w","errorCode":null,"errorMessage":"failed to read archetype file %q: %s: %w","messagePattern":"failed to read archetype file %q: (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/content_factory.go","lineNumber":53,"sourceCode":"// 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{\n\t\tType: archetypeKind,\n\t\tDate: htime.Now().Format(time.RFC3339),\n\t\tPage: p,\n\t\tFile: p.File(),\n\t}","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/content_factory.go#L35-L71","documentation":"After locating the archetype file, Hugo reads its full contents via the file's metadata reader before parsing it as a template; if the read fails (permission denied, broken symlink, I/O error from the virtual filesystem) content creation aborts with this error naming the archetype filename.","triggerScenarios":"`hugo new content ...` where fi.Meta().ReadAll() on the resolved archetype file fails — unreadable permissions, a symlinked archetype whose target is missing, or an error from a module-mounted filesystem.","commonSituations":"Archetype files with restrictive permissions (e.g. created by root/CI), dangling symlinks in archetypes/ after moving a theme, or theme modules not fully fetched so the mounted file can't be read.","solutions":["Check permissions on the reported archetype file (`chmod 644`) and that the running user can read it.","If it's a symlink, fix or replace it with a real file.","If the archetype comes from a module/theme, run `hugo mod get -u` / ensure the theme is fully vendored and present."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Confirm the archetype file exists and is readable before hugo new\nif _, err := os.Stat(filepath.Join(\"archetypes\", kind+\".md\")); err != nil && !os.IsNotExist(err) {\n    return fmt.Errorf(\"archetype unreadable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := create.NewContent(h, kind, target); err != nil {\n    var perr *fs.PathError\n    if errors.As(err, &perr) {\n        // permission or I/O problem reading the archetype file — fix file perms/encoding\n    }\n    return err\n}","preventionTips":["Keep archetype files readable (correct permissions, not symlinks to missing targets)","Store archetypes in the project or theme `archetypes/` dir with UTF-8 encoding","Since the error wraps the underlying cause (%w), use errors.As to distinguish permission vs. not-exist"],"tags":["hugo","archetypes","io","permissions"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}