gohugoio/hugo · error

failed to walk archetype dir %q: %w

Error message

failed to walk archetype dir %q: %w

What it means

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).

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 8a468df065)

Solutions

1. Read the wrapped error to identify the specific file, then fix its permissions or remove the broken symlink inside the archetype directory.
2. Ensure the whole archetypes/<kind>/ tree is readable by the user running hugo.
3. If the archetype comes from a module, clear/refresh the module cache (`hugo mod clean`) to repair corrupted files.

if fi, err := os.Stat(archetypeDir); err != nil || !fi.IsDir() {
    return fmt.Errorf("archetype dir %q missing or not a directory", archetypeDir)
}

func isFSErr(err error) bool {
    var pe *fs.PathError
    return errors.As(err, &pe)
}

if err := create.NewContent(...); err != nil {
    var pe *fs.PathError
    if errors.As(err, &pe) {
        // report pe.Path — broken entry inside the archetype bundle
    }
    return err
}

When it happens

Trigger: `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.

Common situations: 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.

Related errors

• failed to open non-content file: %w
• walk: stat: %s
• walk: open: path: %q filename: %q: %s
• failed to save file %q:: %w
• failed to save file %q: %s

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/830b4527b3dad98d.json. Report an issue: GitHub ↗.