What causes "failed to read archetype file %q: %s: %w" in gohugoio/hugo?

Check permissions on the reported archetype file (`chmod 644`) and that the running user can read it.

failed to read archetype file %q: %s: %w

Error message

failed to read archetype file %q: %s: %w

What it means

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.

Source

Thrown at hugolib/content_factory.go:53

// ContentFactory creates content files from archetype templates.
type ContentFactory struct {
	h *HugoSites

	// We parse the archetype templates as Go templates, so we need
	// to replace any shortcode with a temporary placeholder.
	shortcodeReplacerPre  *strings.Replacer
	shortcodeReplacerPost *strings.Replacer
}

// ApplyArchetypeFilename archetypeFilename to w as a template using the given Page p as the foundation for the data context.
func (f ContentFactory) ApplyArchetypeFi(w io.Writer, p page.Page, archetypeKind string, fi hugofs.FileMetaInfo) error {
	if fi.IsDir() {
		return fmt.Errorf("archetype directory (%q) not supported", fi.Meta().Filename)
	}

	templateSource, err := fi.Meta().ReadAll()
	if err != nil {
		return fmt.Errorf("failed to read archetype file %q: %s: %w", fi.Meta().Filename, err, err)
	}

	return f.ApplyArchetypeTemplate(w, p, archetypeKind, string(templateSource))
}

// ApplyArchetypeTemplate templateSource to w as a template using the given Page p as the foundation for the data context.
func (f ContentFactory) ApplyArchetypeTemplate(w io.Writer, p page.Page, archetypeKind, templateSource string) error {
	ps := p.(*pageState)
	if archetypeKind == "" {
		archetypeKind = p.Type()
	}

	d := &archetypeFileData{
		Type: archetypeKind,
		Date: htime.Now().Format(time.RFC3339),
		Page: p,
		File: p.File(),
	}

View on GitHub ↗ (pinned to 8a468df065)

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.

Defensive patterns

Strategy: try-catch

Validate before calling

// Confirm the archetype file exists and is readable before hugo new
if _, err := os.Stat(filepath.Join("archetypes", kind+".md")); err != nil && !os.IsNotExist(err) {
    return fmt.Errorf("archetype unreadable: %w", err)
}

Try / catch

if err := create.NewContent(h, kind, target); err != nil {
    var perr *fs.PathError
    if errors.As(err, &perr) {
        // permission or I/O problem reading the archetype file — fix file perms/encoding
    }
    return err
}

Prevention

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

When it happens

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

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

Related errors

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