{"record":{"id":"cb0db0d342915719","repo":"gohugoio/hugo","slug":"build-filesystems-w","errorCode":null,"errorMessage":"build filesystems: %w","messagePattern":"build filesystems: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"hugolib/filesystems/basefs.go","lineNumber":515,"sourceCode":"\t\tPublishFsStatic: publishFsStatic,\n\t\tworkingDir:      p.Cfg.BaseConfig().WorkingDir,\n\t\tbuildMu:         buildMu,\n\t}\n\n\tfor _, opt := range options {\n\t\tif err := opt(b); err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t}\n\n\tif b.theBigFs != nil && b.SourceFilesystems != nil {\n\t\treturn b, nil\n\t}\n\n\tbuilder := newSourceFilesystemsBuilder(p, logger, b)\n\tsourceFilesystems, err := builder.Build()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"build filesystems: %w\", err)\n\t}\n\n\tb.SourceFilesystems = sourceFilesystems\n\tb.theBigFs = builder.theBigFs\n\n\treturn b, nil\n}\n\ntype sourceFilesystemsBuilder struct {\n\tlogger   loggers.Logger\n\tp        *paths.Paths\n\tsourceFs afero.Fs\n\tresult   *SourceFilesystems\n\ttheBigFs *filesystemsCollector\n}\n\nfunc newSourceFilesystemsBuilder(p *paths.Paths, logger loggers.Logger, b *BaseFs) *sourceFilesystemsBuilder {\n\tsourceFs := hugofs.NewBaseFileDecorator(p.Fs.Source)","sourceCodeStart":497,"sourceCodeEnd":533,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/hugolib/filesystems/basefs.go#L497-L533","documentation":"A top-level wrapper emitted by the BaseFs constructor when sourceFilesystemsBuilder.Build() fails. It indicates that constructing Hugo's composite source filesystems (content, layouts, assets, data, etc.) failed; the real cause is in the %w chain.","triggerScenarios":"Raised at hugolib/filesystems/basefs.go:515 when builder.Build() returns an error — almost always the wrapped 'create main fs: %w' from createMainOverlayFs failing (overlay/mount construction error).","commonSituations":"Invalid or missing mount directories in config; theme or module directories that don't exist or aren't readable; symlink resolution failures while building the overlay filesystem; corrupt hugo cache under .hugo_cache.","solutions":["Read the wrapped error — it usually points to 'create main fs' and then the concrete I/O or mount error.","Verify every [[mounts]] source path and theme/module component dir exists and is readable.","Clear the Hugo cache (HUGO_CACHEDIR / ~/.cache/hugo_cache) and rebuild.","Run with --verbose or -e to print the full mount list and confirm paths resolve."],"exampleFix":"// before\ntheme = \"my-theme\"   // theme dir absent or misnamed in themes/\n\n// after\ntheme = \"mytheme\"     // matches the actual themes/mytheme directory","handlingStrategy":"validation","validationCode":"// Pre-flight: every mount/theme dir must exist and be readable before building.\nfor _, m := range cfg.Mounts {\n    if _, err := os.Stat(m.Source); err != nil {\n        return fmt.Errorf(\"mount source missing: %s: %w\", m.Source, err)\n    }\n}","typeGuard":null,"tryCatchPattern":"base, err := filesystems.NewBaseFs(p, opts...)\nif err != nil {\n    // construction failed; report and abort — do not proceed to build\n    return err\n}","preventionTips":["Run `hugo config --renderSegments`/verbose to dump resolved mounts before building.","Keep theme/module directories vendored or fetched before build.","Pin Hugo version to avoid overlay-fs behavior changes."],"tags":["filesystem","initialization","mounts","hugo"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}