gohugoio/hugo · critical

build filesystems: %w

Error message

build filesystems: %w

What it means

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.

Source

Thrown at hugolib/filesystems/basefs.go:521

		PublishFsStatic: publishFsStatic,
		workingDir:      p.Cfg.BaseConfig().WorkingDir,
		buildMu:         buildMu,
	}

	for _, opt := range options {
		if err := opt(b); err != nil {
			return nil, err
		}
	}

	if b.theBigFs != nil && b.SourceFilesystems != nil {
		return b, nil
	}

	builder := newSourceFilesystemsBuilder(p, logger, b)
	sourceFilesystems, err := builder.Build()
	if err != nil {
		return nil, fmt.Errorf("build filesystems: %w", err)
	}

	b.SourceFilesystems = sourceFilesystems
	b.theBigFs = builder.theBigFs

	return b, nil
}

type sourceFilesystemsBuilder struct {
	logger   loggers.Logger
	p        *paths.Paths
	sourceFs afero.Fs
	result   *SourceFilesystems
	theBigFs *filesystemsCollector
}

func newSourceFilesystemsBuilder(p *paths.Paths, logger loggers.Logger, b *BaseFs) *sourceFilesystemsBuilder {
	sourceFs := hugofs.NewBaseFileDecorator(p.Fs.Source)

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Read the wrapped error — it usually names the failing mount or directory; fix the `source` path or create the missing directory.
2. Ensure themes/modules are actually present: run `git submodule update --init --recursive` or `hugo mod tidy && hugo mod get` before building.
3. Check `[[module.mounts]]` entries for typos and correct component targets (content, layouts, assets, static, data, i18n, archetypes).

Example fix

# before
[[module.mounts]]
source = "asets"
target = "assets"
# after
[[module.mounts]]
source = "assets"
target = "assets"

# Sanity-check module setup before building:
hugo mod verify && hugo mod graph

if err := build(); err != nil {
    if strings.Contains(err.Error(), "build filesystems") {
        // usually a bad mount, missing module, or unreadable dir
        log.Println("check [[module.mounts]] sources exist and hugo mod get has run")
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to vendor module: %w
• failed to copy module to vendor dir: %w
• failed to make target dir: %w
• failed to copy module file to vendor: %w
• failed to copy resources to vendor dir: %w

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/cb0db0d342915719.json. Report an issue: GitHub ↗.