gohugoio/hugo · critical

create main fs: %w

Error message

create main fs: %w

What it means

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.

Source

Thrown at hugolib/filesystems/basefs.go:554

		result: &SourceFilesystems{
			conf: p.Cfg,
		},
	}
}

func (b *sourceFilesystemsBuilder) newSourceFilesystem(name string, fs afero.Fs) *SourceFilesystem {
	return &SourceFilesystem{
		Name:     name,
		Fs:       fs,
		SourceFs: b.sourceFs,
	}
}

func (b *sourceFilesystemsBuilder) Build() (*SourceFilesystems, error) {
	if b.theBigFs == nil {
		theBigFs, err := b.createMainOverlayFs(b.p)
		if err != nil {
			return nil, fmt.Errorf("create main fs: %w", err)
		}

		b.theBigFs = theBigFs
	}

	createView := func(componentID string, overlayFs *overlayfs.OverlayFs) *SourceFilesystem {
		if b.theBigFs == nil || b.theBigFs.overlayMounts == nil {
			return b.newSourceFilesystem(componentID, hugofs.NoOpFs)
		}

		fs := hugofs.NewComponentFs(
			hugofs.ComponentFsOptions{
				Fs:        overlayFs,
				Component: componentID,
				Cfg:       b.p.Cfg,
			},
		)

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Unwrap the %w to find the offending path/operation (typically a Stat/Open/MkdirAll failure).
2. Confirm all module/theme/mount source directories exist on disk and are readable.
3. Remove or comment out mounts/modules one at a time to isolate the failing overlay layer.
4. Re-run `hugo mod tidy` to reconcile module state, then rebuild.

Example fix

// before
[[imports]]
path = "github.com/foo/bar"   // not vendored / not downloaded

// after
// run: hugo mod vendor   or   hugo mod tidy
// then ensure the module is resolvable before building

// Ensure all module + theme component roots exist before constructing overlays.
for _, root := range componentRoots { if err := checkReadableDir(root); err != nil { return err } }

sfs, err := builder.Build()
if err != nil {
    return fmt.Errorf("cannot build source filesystems: %w", err) // abort
}

When it happens

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

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

Related errors

• build filesystems: %w
• failled to create base cache directory: %s
• could not determine content directory for %q
• target path "{targetDir}" exists but is not a directory
• target path "{targetDir}" exists and is not empty

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