{"record":{"id":"09caca49891ea7b9","repo":"gohugoio/hugo","slug":"create-main-fs-w","errorCode":null,"errorMessage":"create main fs: %w","messagePattern":"create main fs: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"hugolib/filesystems/basefs.go","lineNumber":554,"sourceCode":"\t\tresult: &SourceFilesystems{\n\t\t\tconf: p.Cfg,\n\t\t},\n\t}\n}\n\nfunc (b *sourceFilesystemsBuilder) newSourceFilesystem(name string, fs afero.Fs) *SourceFilesystem {\n\treturn &SourceFilesystem{\n\t\tName:     name,\n\t\tFs:       fs,\n\t\tSourceFs: b.sourceFs,\n\t}\n}\n\nfunc (b *sourceFilesystemsBuilder) Build() (*SourceFilesystems, error) {\n\tif b.theBigFs == nil {\n\t\ttheBigFs, err := b.createMainOverlayFs(b.p)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"create main fs: %w\", err)\n\t\t}\n\n\t\tb.theBigFs = theBigFs\n\t}\n\n\tcreateView := func(componentID string, overlayFs *overlayfs.OverlayFs) *SourceFilesystem {\n\t\tif b.theBigFs == nil || b.theBigFs.overlayMounts == nil {\n\t\t\treturn b.newSourceFilesystem(componentID, hugofs.NoOpFs)\n\t\t}\n\n\t\tfs := hugofs.NewComponentFs(\n\t\t\thugofs.ComponentFsOptions{\n\t\t\t\tFs:        overlayFs,\n\t\t\t\tComponent: componentID,\n\t\t\t\tCfg:       b.p.Cfg,\n\t\t\t},\n\t\t)\n","sourceCodeStart":536,"sourceCodeEnd":572,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/hugolib/filesystems/basefs.go#L536-L572","documentation":"Returned by sourceFilesystemsBuilder.Build() when createMainOverlayFs() fails to assemble the big overlay filesystem that underpins all component filesystems. This is the root construction step; failure here prevents any component view from being built.","triggerScenarios":"Raised at basefs.go:554 when createMainOverlayFs(p) returns a non-nil error — caused by overlay mount creation, directory walking, or symlink/stat failures while layering project + modules + theme.","commonSituations":"A module or theme directory listed in config does not exist; a mount source has a permission or symlink error; an overlayfs mount collides or references an unreadable path; OS-level path length / encoding issues on the mount source.","solutions":["Unwrap the %w to find the offending path/operation (typically a Stat/Open/MkdirAll failure).","Confirm all module/theme/mount source directories exist on disk and are readable.","Remove or comment out mounts/modules one at a time to isolate the failing overlay layer.","Re-run `hugo mod tidy` to reconcile module state, then rebuild."],"exampleFix":"// before\n[[imports]]\npath = \"github.com/foo/bar\"   // not vendored / not downloaded\n\n// after\n// run: hugo mod vendor   or   hugo mod tidy\n// then ensure the module is resolvable before building","handlingStrategy":"validation","validationCode":"// Ensure all module + theme component roots exist before constructing overlays.\nfor _, root := range componentRoots { if err := checkReadableDir(root); err != nil { return err } }","typeGuard":null,"tryCatchPattern":"sfs, err := builder.Build()\nif err != nil {\n    return fmt.Errorf(\"cannot build source filesystems: %w\", err) // abort\n}","preventionTips":["Validate theme and module paths at startup; fail fast in CI before the build.","Keep a clean checkout; avoid stale symlinks in component directories.","Document the expected directory layout in repo docs for contributors."],"tags":["filesystem","overlay","initialization","mounts","hugo"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}