{"record":{"id":"08f552bbfe34555e","repo":"caddyserver/caddy","slug":"loading-storage-module-v","errorCode":null,"errorMessage":"loading storage module: %v","messagePattern":"loading storage module: (.+?)","errorType":"http","errorClass":null,"httpStatus":500,"severity":"error","filePath":"caddy.go","lineNumber":544,"sourceCode":"\t}\n\terr = newCfg.Logging.openLogs(ctx)\n\tif err != nil {\n\t\treturn ctx, err\n\t}\n\n\t// create the new filesystem map\n\tnewCfg.fileSystems = &filesystems.FileSystemMap{}\n\n\t// prepare the new config for use\n\tnewCfg.apps = make(map[string]App)\n\tnewCfg.failedApps = make(map[string]error)\n\n\t// set up global storage and make it CertMagic's default storage, too\n\terr = func() error {\n\t\tif newCfg.StorageRaw != nil {\n\t\t\tval, err := ctx.LoadModule(newCfg, \"StorageRaw\")\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"loading storage module: %v\", err)\n\t\t\t}\n\t\t\tstor, err := val.(StorageConverter).CertMagicStorage()\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"creating storage value: %v\", err)\n\t\t\t}\n\t\t\tnewCfg.storage = stor\n\t\t}\n\n\t\tif newCfg.storage == nil {\n\t\t\tnewCfg.storage = DefaultStorage\n\t\t}\n\t\tcertmagic.Default.Storage = newCfg.storage\n\n\t\treturn nil\n\t}()\n\tif err != nil {\n\t\treturn ctx, err\n\t}","sourceCodeStart":526,"sourceCodeEnd":562,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/caddy.go#L526-L562","documentation":"While preparing a new config, run() loads the storage module declared in the top-level \"storage\" field via ctx.LoadModule(newCfg, \"StorageRaw\"). If the module cannot be loaded — unknown module name or failed provisioning — the error is wrapped as 'loading storage module'. Storage affects where certificates and state persist, so a failure here aborts the load.","triggerScenarios":"JSON config with \"storage\": {\"module\": \"some_module\", ...} where the module is not compiled into the binary or its Provision() fails (bad connection params, unsupported scheme). Triggered on caddy run and on every admin config load with that storage block.","commonSituations":"Custom builds missing a storage plugin that the config references; Redis/PostgreSQL/S3 storage plugins with invalid endpoints or credentials; version upgrades renaming storage module fields; typo in the module key.","solutions":["Check the wrapped error for the module ID and provisioning detail.","Verify the plugin is present: caddy list-modules | grep -i storage; rebuild with xcaddy build --with <plugin> if missing.","Fix the module's parameters (endpoint URL, credentials, bucket) per its docs.","Temporarily remove the storage block to fall back to DefaultStorage and isolate the issue."],"exampleFix":"// before\n\"storage\": { \"module\": \"redis\", \"adress\": \"localhost:6379\" }  // typo'd field\n\n// after\n\"storage\": { \"module\": \"redis\", \"address\": \"localhost:6379\" }","handlingStrategy":"validation","validationCode":"modName := cfg.StorageRaw[\"module\"].(string) // after JSON decode\nfound := false\nfor _, m := range caddy.DefaultModules { // or 'caddy list-modules' out-of-band\n    if m.ID.String() == \"caddy.storage.\"+modName { found = true }\n}\nif !found { return fmt.Errorf(\"storage module %q not in build\", modName) }","typeGuard":"func isRegisteredStorage(mod caddy.Module) bool {\n    _, ok := mod.(caddy.StorageConverter)\n    return ok\n}","tryCatchPattern":null,"preventionTips":["Build custom binaries with xcaddy and pin plugin versions.","Verify 'caddy list-modules' contains your storage module before deploying its config.","Validate module configs with caddy validate in the target environment."],"tags":["caddy","storage","modules","config","provisioning"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}