{"record":{"id":"6fbcbe9f09dfd92e","repo":"caddyserver/caddy","slug":"loading-file-system-module-v","errorCode":null,"errorMessage":"loading file system module: %v","messagePattern":"loading file system module: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyfs/filesystem.go","lineNumber":66,"sourceCode":"\n// CaddyModule returns the Caddy module information.\nfunc (Filesystems) CaddyModule() caddy.ModuleInfo {\n\treturn caddy.ModuleInfo{\n\t\tID:  \"caddy.filesystems\",\n\t\tNew: func() caddy.Module { return new(Filesystems) },\n\t}\n}\n\nfunc (xs *Filesystems) Start() error { return nil }\nfunc (xs *Filesystems) Stop() error  { return nil }\n\nfunc (xs *Filesystems) Provision(ctx caddy.Context) error {\n\t// load the filesystem module\n\tfor _, f := range xs.Filesystems {\n\t\tif len(f.FileSystemRaw) > 0 {\n\t\t\tmod, err := ctx.LoadModule(f, \"FileSystemRaw\")\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"loading file system module: %v\", err)\n\t\t\t}\n\t\t\tf.fileSystem = mod.(fs.FS)\n\t\t}\n\t\t// register that module\n\t\tctx.Logger().Debug(\"registering fs\", zap.String(\"fs\", f.Key))\n\t\tctx.FileSystems().Register(f.Key, f.fileSystem)\n\t\t// remember to unregister the module when we are done\n\t\txs.defers = append(xs.defers, func() {\n\t\t\tctx.Logger().Debug(\"unregistering fs\", zap.String(\"fs\", f.Key))\n\t\t\tctx.FileSystems().Unregister(f.Key)\n\t\t})\n\t}\n\treturn nil\n}\n\nfunc (f *Filesystems) Cleanup() error {\n\tfor _, v := range f.defers {\n\t\tv()","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyfs/filesystem.go#L48-L84","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the wrapped LoadModule error for the concrete cause.","Correct the module ID or rebuild with xcaddy to include the file system plugin.","Ensure the fs block is defined in the same config that references it via its key.","List available modules with 'caddy list-modules | grep caddy.fs'."],"exampleFix":"// before (json)\n\"file_systems\": [{\"key\": \"myfs\", \"file_system\": {\"bad_fs\": {}}}]\n\n// after\n\"file_systems\": [{\"key\": \"myfs\", \"file_system\": {\"caddy.fs.local\": {\"root\": \"/srv\"}}}]","handlingStrategy":"validation","validationCode":"// verify each fs module id and that referenced keys are defined\nfor _, fsEntry := range fsEntries(cfg) {\n    if _, err := caddy.GetModule(fsEntry.ModuleID); err != nil {\n        return fmt.Errorf(\"fs module %s not in build: %w\", fsEntry.ModuleID, err)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := caddy.Validate(cfg); err != nil {\n    if strings.Contains(err.Error(), \"loading file system module\") {\n        // fix module id or rebuild with the fs plugin\n    }\n    return err\n}","preventionTips":["Define file_systems before referencing their keys in file_server.","Include fs plugins explicitly in xcaddy builds and lock versions.","Validate the full config atomically — fs and http apps load together."],"tags":["filesystem","module-system","provisioning"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}