gohugoio/hugo · error

failed to walk archetype dir

Error message

failed to walk archetype dir %q: %w

What it means

When the archetype is a directory, contentBuilder.mapArcheTypeDir walks it via hugofs.NewWalkway (create/content.go:335). This wraps any error returned by the walk, e.g. an unreadable entry, a symlink loop, or an FS-level error inside the archetype tree.

Solutions

1. Scan the archetype directory for permission issues, symlink loops, and broken links, then fix them.
2. Simplify the directory archetype to a minimal tree and re-add entries to isolate the failing one.
3. Ensure the archetypes/ path is on a healthy, readable filesystem.

Example fix

# before: archetypes/default/ contains a self-referential symlink
ln -s . archetypes/default/loop

# after: remove the loop
$ rm archetypes/default/loop

// Walk the archetype directory ahead of time to surface FS issues early.
func ValidateArchetypeDir(fs afero.Fs, root string) error {
    return afero.Walk(fs, root, func(p string, info os.FileInfo, err error) error {
        return err // any walk error propagates
    })
}

if err := create.NewContent(h, kind, targetPath, force); err != nil {
    return err
}

When it happens

Trigger: The archetype directory contains an unreadable file/subdir, a symlink that loops, or a virtual mount whose backing path is missing; the walk closure returns a non-nil error for one of the entries.

Common situations: Symlink loop inside archetypes/; archetype directory on a flaky mount; archetype copied from a different OS with case-collision filenames.

Related errors

• archetype directory ( ) not supported
• failed to open non-content file
• failed to read archetype file
• walk: open: path: filename
• walk: Readdir

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/830b4527b3dad98d. Report an issue: GitHub.

Appendix: source

Thrown at create/content.go:338

			}
			return nil
		}

		m.otherFiles = append(m.otherFiles, fim)

		return nil
	}

	walkCfg := hugofs.WalkwayConfig{
		WalkFn: walkFn,
		Fs:     b.archeTypeFs,
		Root:   filepath.FromSlash(b.archetypeFi.Meta().PathInfo.Path()),
	}

	w := hugofs.NewWalkway(walkCfg)

	if err := w.Walk(); err != nil {
		return fmt.Errorf("failed to walk archetype dir %q: %w", b.archetypeFi.Meta().Filename, err)
	}

	b.dirMap = m

	return nil
}

func (b *contentBuilder) openInEditorIfConfigured(filename string) error {
	editor := b.h.Conf.NewContentEditor()
	if editor == "" {
		return nil
	}

	editorExec := strings.Fields(editor)[0]
	editorFlags := strings.Fields(editor)[1:]

	var args []any
	for _, editorFlag := range editorFlags {

View on GitHub (pinned to 52c9bd7908)