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

Retry after ensuring the archetype file is fully present locally (force-download cloud-synced placeholders).

failed to read archetype file: %w

Error message

failed to read archetype file: %w

What it means

usesSiteVar opens an archetype content file and reads it fully to check whether it references `.Site` or `site.` — that determines whether Hugo must build the whole site before executing the archetype template (expensive) or can use a filtered build. This error means io.ReadAll on the opened archetype file failed mid-read, wrapping the underlying I/O error (the earlier Open error is returned unwrapped).

Source

Thrown at create/content.go:388

	if err != nil {
		return err
	}

	return cmd.Run()
}

func (b *contentBuilder) usesSiteVar(fi hugofs.FileMetaInfo) (bool, error) {
	if fi == nil {
		return false, nil
	}
	f, err := fi.Meta().Open()
	if err != nil {
		return false, err
	}
	defer f.Close()
	bb, err := io.ReadAll(f)
	if err != nil {
		return false, fmt.Errorf("failed to read archetype file: %w", err)
	}

	return bytes.Contains(bb, []byte(".Site")) || bytes.Contains(bb, []byte("site.")), nil
}

type archetypeMap struct {
	// These needs to be parsed and executed as Go templates.
	contentFiles []hugofs.FileMetaInfo
	// These are just copied to destination.
	otherFiles []hugofs.FileMetaInfo
	// If the templates needs a fully built site. This can potentially be
	// expensive, so only do when needed.
	siteUsed bool
}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Retry after ensuring the archetype file is fully present locally (force-download cloud-synced placeholders).
Check the wrapped error for the OS-level cause and verify the disk/mount health.
If the archetype is module-provided, run `hugo mod clean && hugo mod get` to re-fetch intact files.

Defensive patterns

Strategy: try-catch

Validate before calling

b, err := os.ReadFile(filepath.Join("archetypes", "default.md"))
if err != nil { return err }
_ = b // confirm readable, non-empty template

Type guard

func isReadErr(err error) bool { return errors.Is(err, fs.ErrPermission) || errors.Is(err, fs.ErrNotExist) }

Try / catch

if err := create.NewContent(...); err != nil {
    if strings.Contains(err.Error(), "failed to read archetype file") {
        // check the archetype file's permissions and encoding
    }
    return err
}

Prevention

Keep archetype files as plain readable text (UTF-8), correct permissions
Don't point archetypes at symlinks resolving outside the readable tree
Verify theme archetypes are present after theme updates or submodule checkouts

When it happens

Trigger: During `hugo new content`, for the single archetype file (buildFile) or each content file in a directory archetype (mapArcheTypeDir walk), when reading the file's bytes fails: I/O errors on the underlying storage, the file truncated/removed mid-read, or errors from a virtual/module filesystem layer.

Common situations: Flaky network filesystems or cloud-synced folders (Dropbox/OneDrive placeholder files that fail to hydrate); archetype files from a corrupted Hugo module cache; disk errors.

Related errors

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