gohugoio/hugo · critical

build filesystems

Error message

build filesystems: %w

What it means

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.

Solutions

1. Read the wrapped error — it usually points to 'create main fs' and then the concrete I/O or mount error.
2. Verify every [[mounts]] source path and theme/module component dir exists and is readable.
3. Clear the Hugo cache (HUGO_CACHEDIR / ~/.cache/hugo_cache) and rebuild.
4. Run with --verbose or -e to print the full mount list and confirm paths resolve.

Example fix

// before
theme = "my-theme"   // theme dir absent or misnamed in themes/

// after
theme = "mytheme"     // matches the actual themes/mytheme directory

// Pre-flight: every mount/theme dir must exist and be readable before building.
for _, m := range cfg.Mounts {
    if _, err := os.Stat(m.Source); err != nil {
        return fmt.Errorf("mount source missing: %s: %w", m.Source, err)
    }
}

base, err := filesystems.NewBaseFs(p, opts...)
if err != nil {
    // construction failed; report and abort — do not proceed to build
    return err
}

When it happens

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

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

Related errors

• create main fs
• could not determine content directory for
• failled to create base cache directory
• abort: jekyll root contains neither posts nor drafts
• already exists

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/cb0db0d342915719. Report an issue: GitHub.

Appendix: source

Thrown at hugolib/filesystems/basefs.go:515

		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 52c9bd7908)