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

Check read permission on the archetype file named in the error and chmod/chown as needed.

failed to read archetype file

Error message

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

What it means

Returned by ApplyArchetypeFi when fi.Meta().ReadAll() fails reading the archetype file's bytes. The wrapped chain redundantly includes the error twice (%s then %w) so the message shows both the formatted and unwrapped form. Reading happens after the IsDir check passed, so the file existed as a file but could not be read.

Solutions

Check read permission on the archetype file named in the error and chmod/chown as needed.
Confirm the archetype file is a regular file, not a broken symlink.
Re-read after any sync/generation step that may have been mid-write.
If the archetype is on a custom mount, verify the mount source is healthy.

Defensive patterns

Strategy: validation

Validate before calling

f, err := os.Open(archetypePath)
if err != nil { /* preflight read-permission check */ }
defer f.Close()
if _, err := f.Stat(); err != nil { /* not a readable regular file */ }

Try / catch

if err := cf.ApplyArchetypeFi(w, p, kind, fi); err != nil {
    if strings.Contains(err.Error(), "failed to read archetype file") { /* check perms, then retry */ }
}

Prevention

Verify archetype files are world-readable in the repo (avoid committing 600).
Ensure archetype files are regular files, not broken symlinks.
Pause sync tools that rewrite archetypes mid-build.

When it happens

Trigger: The archetype file exists but ReadAll errors — permission denied reading it, file truncated/removed between Stat and ReadAll, encoding issue, or a backing fs whose Open/Read fails. Triggered during `hugo new` and any ApplyArchetypeFi caller.

Common situations: archetypes/*.md file with restrictive perms (e.g. committed with 600 owned by another user); archetype lives on a mount that dropped; file replaced mid-operation by a sync tool; broken symlink archetype.

Related errors

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

Appendix: 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 52c9bd7908)