{"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":521,"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":503,"sourceCodeEnd":539,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/filesystems/basefs.go#L503-L539","documentation":"During `BaseFs` construction Hugo builds the composite source filesystems (content, layouts, assets, static, data, i18n, archetypes) from the project, themes, and module mounts. Any failure in `sourceFilesystemsBuilder.Build()` — a bad mount, missing module directory, or overlay-filesystem error — is wrapped here and aborts site initialization before anything renders.","triggerScenarios":"Site startup (`hugo`, `hugo server`) where `newSourceFilesystemsBuilder(p, logger, b).Build()` fails: a `[[module.mounts]]` entry whose `source` doesn't exist or is a file where a directory is expected, an unresolvable theme/module component dir, duplicate/conflicting mount targets, or symlink resolution errors.","commonSituations":"Typos in `source`/`target` of module mounts; themes not fetched (`git submodule update --init` or `hugo mod get` not run) so mounted dirs are missing; case-sensitivity mismatches moving between macOS and Linux CI; mounting individual files with directory semantics.","solutions":["Read the wrapped error — it usually names the failing mount or directory; fix the `source` path or create the missing directory.","Ensure themes/modules are actually present: run `git submodule update --init --recursive` or `hugo mod tidy && hugo mod get` before building.","Check `[[module.mounts]]` entries for typos and correct component targets (content, layouts, assets, static, data, i18n, archetypes)."],"exampleFix":"# before\n[[module.mounts]]\nsource = \"asets\"\ntarget = \"assets\"\n# after\n[[module.mounts]]\nsource = \"assets\"\ntarget = \"assets\"","handlingStrategy":"try-catch","validationCode":"# Sanity-check module setup before building:\nhugo mod verify && hugo mod graph","typeGuard":null,"tryCatchPattern":"if err := build(); err != nil {\n    if strings.Contains(err.Error(), \"build filesystems\") {\n        // usually a bad mount, missing module, or unreadable dir\n        log.Println(\"check [[module.mounts]] sources exist and hugo mod get has run\")\n    }\n    return err\n}","preventionTips":["Run `hugo mod get`/`hugo mod tidy` so all mounted modules are present before building","Ensure every [[module.mounts]] source directory exists (Hugo won't create them)","Check directory permissions on themes/, content/, and mounted paths","Pin module versions in go.mod to avoid CI resolving a broken upstream"],"tags":["hugo","filesystem","modules","startup"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}