caddyserver/caddy · error

loading file system module: %v

Error message

loading file system module: %v

What it means

The caddyfs (file systems) app's Provision loads each named file system module from its FileSystemRaw config via ctx.LoadModule and registers it under its key. Failures in module resolution or the module's own provisioning (e.g. a bad file system backend config) surface wrapped here.

Source

Thrown at modules/caddyfs/filesystem.go:66

// CaddyModule returns the Caddy module information.
func (Filesystems) CaddyModule() caddy.ModuleInfo {
	return caddy.ModuleInfo{
		ID:  "caddy.filesystems",
		New: func() caddy.Module { return new(Filesystems) },
	}
}

func (xs *Filesystems) Start() error { return nil }
func (xs *Filesystems) Stop() error  { return nil }

func (xs *Filesystems) Provision(ctx caddy.Context) error {
	// load the filesystem module
	for _, f := range xs.Filesystems {
		if len(f.FileSystemRaw) > 0 {
			mod, err := ctx.LoadModule(f, "FileSystemRaw")
			if err != nil {
				return fmt.Errorf("loading file system module: %v", err)
			}
			f.fileSystem = mod.(fs.FS)
		}
		// register that module
		ctx.Logger().Debug("registering fs", zap.String("fs", f.Key))
		ctx.FileSystems().Register(f.Key, f.fileSystem)
		// remember to unregister the module when we are done
		xs.defers = append(xs.defers, func() {
			ctx.Logger().Debug("unregistering fs", zap.String("fs", f.Key))
			ctx.FileSystems().Unregister(f.Key)
		})
	}
	return nil
}

func (f *Filesystems) Cleanup() error {
	for _, v := range f.defers {
		v()

View on GitHub (pinned to 50e54ee279)

Solutions

1. Check the wrapped LoadModule error for the concrete cause.
2. Correct the module ID or rebuild with xcaddy to include the file system plugin.
3. Ensure the fs block is defined in the same config that references it via its key.
4. List available modules with 'caddy list-modules | grep caddy.fs'.

Example fix

// before (json)
"file_systems": [{"key": "myfs", "file_system": {"bad_fs": {}}}]

// after
"file_systems": [{"key": "myfs", "file_system": {"caddy.fs.local": {"root": "/srv"}}}]

// verify each fs module id and that referenced keys are defined
for _, fsEntry := range fsEntries(cfg) {
    if _, err := caddy.GetModule(fsEntry.ModuleID); err != nil {
        return fmt.Errorf("fs module %s not in build: %w", fsEntry.ModuleID, err)
    }
}

if err := caddy.Validate(cfg); err != nil {
    if strings.Contains(err.Error(), "loading file system module") {
        // fix module id or rebuild with the fs plugin
    }
    return err
}

When it happens

Trigger: A file_systems config naming an unregistered fs module, or one whose backend configuration (paths, options) fails provisioning — for example a third-party S3/embedded-fs plugin with invalid options.

Common situations: Custom builds without the fs plugin; typo'd module IDs; referencing file systems by key in file_server before defining them in file_systems; schema changes in plugin upgrades.

Related errors

• %v; additionally, cleanup: %v
• provision %s: %v
• opening log writer using %#v: %v
• loading event subscriber modules: %v
• --input is required

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/6fbcbe9f09dfd92e. Report an issue: GitHub.