{"id":"830b4527b3dad98d","repo":"gohugoio/hugo","slug":"failed-to-walk-archetype-dir-q-w","errorCode":null,"errorMessage":"failed to walk archetype dir %q: %w","messagePattern":"failed to walk archetype dir %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"create/content.go","lineNumber":338,"sourceCode":"\t\t\t}\n\t\t\treturn nil\n\t\t}\n\n\t\tm.otherFiles = append(m.otherFiles, fim)\n\n\t\treturn nil\n\t}\n\n\twalkCfg := hugofs.WalkwayConfig{\n\t\tWalkFn: walkFn,\n\t\tFs:     b.archeTypeFs,\n\t\tRoot:   filepath.FromSlash(b.archetypeFi.Meta().PathInfo.Path()),\n\t}\n\n\tw := hugofs.NewWalkway(walkCfg)\n\n\tif err := w.Walk(); err != nil {\n\t\treturn fmt.Errorf(\"failed to walk archetype dir %q: %w\", b.archetypeFi.Meta().Filename, err)\n\t}\n\n\tb.dirMap = m\n\n\treturn nil\n}\n\nfunc (b *contentBuilder) openInEditorIfConfigured(filename string) error {\n\teditor := b.h.Conf.NewContentEditor()\n\tif editor == \"\" {\n\t\treturn nil\n\t}\n\n\teditorExec := strings.Fields(editor)[0]\n\teditorFlags := strings.Fields(editor)[1:]\n\n\tvar args []any\n\tfor _, editorFlag := range editorFlags {","sourceCodeStart":320,"sourceCodeEnd":356,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/create/content.go#L320-L356","documentation":"When the selected archetype is a directory, mapArcheTypeDir walks it with hugofs.NewWalkway to classify files into template-executed content files and copy-as-is other files. This error wraps any failure during that walk — an unreadable subdirectory/file, a broken symlink, or an error from the per-file callback (which also reads content files to detect .Site/site. usage).","triggerScenarios":"`hugo new content <bundle-path>` with a directory archetype (archetypes/<kind>/ or archetypes/default/) when the filesystem walk over that directory fails: permission errors on entries, dangling symlinks, or usesSiteVar failing to open/read a content file inside the archetype during the walk.","commonSituations":"Theme/module archetype directories with restrictive permissions after packaging; symlinked archetype assets that don't resolve in the build environment (Docker, CI checkouts without symlink support); corrupted module cache.","solutions":["Read the wrapped error to identify the specific file, then fix its permissions or remove the broken symlink inside the archetype directory.","Ensure the whole archetypes/<kind>/ tree is readable by the user running hugo.","If the archetype comes from a module, clear/refresh the module cache (`hugo mod clean`) to repair corrupted files."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if fi, err := os.Stat(archetypeDir); err != nil || !fi.IsDir() {\n    return fmt.Errorf(\"archetype dir %q missing or not a directory\", archetypeDir)\n}","typeGuard":"func isFSErr(err error) bool {\n    var pe *fs.PathError\n    return errors.As(err, &pe)\n}","tryCatchPattern":"if err := create.NewContent(...); err != nil {\n    var pe *fs.PathError\n    if errors.As(err, &pe) {\n        // report pe.Path — broken entry inside the archetype bundle\n    }\n    return err\n}","preventionTips":["Keep archetype bundle directories free of broken symlinks and unreadable entries","Ensure the whole archetypes tree is committed and readable in CI","Test bundle archetypes (archetypes/<kind>/) locally after changes"],"tags":["hugo","archetype","filesystem","walk","permissions"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}