gohugoio/hugo · error

failed to read archetype file

Error message

failed to read archetype file: %w

What it means

contentBuilder.usesSiteVar (create/content.go:386) opens the archetype file and reads it fully with io.ReadAll to detect whether it references .Site or site. (which decides whether a full site build is needed). This wraps a ReadAll failure on the already-opened archetype file.

Solutions

1. Verify the archetype file is readable in full (cat it, checksum it).
2. Recreate the archetype file from a known-good source.
3. Move archetypes/ off a flaky/network mount onto local disk.

Example fix

# before: archetypes/default.md is truncated/corrupt
$ cat archetypes/default.md   # reads partway then errors

# after: rewrite the archetype
$ cat > archetypes/default.md <<'EOF'
---
title: "{{ replace .File.ContentBaseName "-" " " | title }}"
date: {{ .Date }}
draft: true
---
EOF

// Read-check the archetype file before NewContent.
func ValidateArchetypeReadable(fs afero.Fs, path string) error {
    f, err := fs.Open(path)
    if err != nil { return err }
    defer f.Close()
    if _, err := io.ReadAll(f); err != nil { return err }
    return nil
}

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

When it happens

Trigger: The archetype file opens but cannot be read end-to-end: an intermittent IO error, the file truncates or is removed mid-read, or a virtual FS reports a read error.

Common situations: Archetype file on a network/flaky mount; file replaced while Hugo is running; corruption on the archetypes volume.

Related errors

• archetype directory ( ) not supported
• failed to open non-content file
• failed to walk archetype dir
• abort: jekyll root contains neither posts nor drafts
• build filesystems

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

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