{"id":"bbe1d049713c6df4","repo":"gohugoio/hugo","slug":"failed-to-read-archetype-file-w","errorCode":null,"errorMessage":"failed to read archetype file: %w","messagePattern":"failed to read archetype file: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"create/content.go","lineNumber":388,"sourceCode":"\tif err != nil {\n\t\treturn err\n\t}\n\n\treturn cmd.Run()\n}\n\nfunc (b *contentBuilder) usesSiteVar(fi hugofs.FileMetaInfo) (bool, error) {\n\tif fi == nil {\n\t\treturn false, nil\n\t}\n\tf, err := fi.Meta().Open()\n\tif err != nil {\n\t\treturn false, err\n\t}\n\tdefer f.Close()\n\tbb, err := io.ReadAll(f)\n\tif err != nil {\n\t\treturn false, fmt.Errorf(\"failed to read archetype file: %w\", err)\n\t}\n\n\treturn bytes.Contains(bb, []byte(\".Site\")) || bytes.Contains(bb, []byte(\"site.\")), nil\n}\n\ntype archetypeMap struct {\n\t// These needs to be parsed and executed as Go templates.\n\tcontentFiles []hugofs.FileMetaInfo\n\t// These are just copied to destination.\n\totherFiles []hugofs.FileMetaInfo\n\t// If the templates needs a fully built site. This can potentially be\n\t// expensive, so only do when needed.\n\tsiteUsed bool\n}\n","sourceCodeStart":370,"sourceCodeEnd":403,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/create/content.go#L370-L403","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"b, err := os.ReadFile(filepath.Join(\"archetypes\", \"default.md\"))\nif err != nil { return err }\n_ = b // confirm readable, non-empty template","typeGuard":"func isReadErr(err error) bool { return errors.Is(err, fs.ErrPermission) || errors.Is(err, fs.ErrNotExist) }","tryCatchPattern":"if err := create.NewContent(...); err != nil {\n    if strings.Contains(err.Error(), \"failed to read archetype file\") {\n        // check the archetype file's permissions and encoding\n    }\n    return err\n}","preventionTips":["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"],"tags":["hugo","archetype","io","filesystem"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}