{"record":{"id":"dc2fe23947b6aefc","repo":"caddyserver/caddy","slug":"creating-storage-configuration-v","errorCode":null,"errorMessage":"creating storage configuration: %v","messagePattern":"creating storage configuration: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddypki/ca.go","lineNumber":118,"sourceCode":"\tca.mu = new(sync.RWMutex)\n\tca.log = log.Named(\"ca.\" + id)\n\tca.ctx = ctx\n\n\tif id == \"\" {\n\t\treturn fmt.Errorf(\"CA ID is required (use 'local' for the default CA)\")\n\t}\n\tca.mu.Lock()\n\tca.ID = id\n\tca.mu.Unlock()\n\n\tif ca.StorageRaw != nil {\n\t\tval, err := ctx.LoadModule(ca, \"StorageRaw\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"loading storage module: %v\", err)\n\t\t}\n\t\tcmStorage, err := val.(caddy.StorageConverter).CertMagicStorage()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"creating storage configuration: %v\", err)\n\t\t}\n\t\tca.storage = cmStorage\n\t}\n\tif ca.storage == nil {\n\t\tca.storage = ctx.Storage()\n\t}\n\n\tif ca.Name == \"\" {\n\t\tca.Name = defaultCAName\n\t}\n\tif ca.RootCommonName == \"\" {\n\t\tca.RootCommonName = defaultRootCommonName\n\t}\n\tif ca.IntermediateCommonName == \"\" {\n\t\tca.IntermediateCommonName = defaultIntermediateCommonName\n\t}\n\tif ca.IntermediateLifetime == 0 {\n\t\tca.IntermediateLifetime = caddy.Duration(defaultIntermediateLifetime)","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddypki/ca.go#L100-L136","documentation":"Returned by CA.Provision when the loaded storage module's CertMagicStorage() conversion fails — i.e. the module was found and instantiated, but it either does not properly implement caddy.StorageConverter or its own conversion to a certmagic.Storage returned an error. This sits between module loading (previous error) and storage use: the module exists but cannot produce a usable storage backend for this CA.","triggerScenarios":"A storage plugin whose CertMagicStorage() returns an error — invalid connection options (bad URL, missing credentials), unsupported configuration keys, or a plugin version whose conversion signature/behavior is incompatible with the Caddy version in use. The %v wraps the conversion error.","commonSituations":"Plugin version skew after upgrading Caddy (plugin compiled against an older certmagic); storage module config with missing required options (e.g. redis without an address); secrets provided as env vars that are empty at provisioning time; a third-party module that lazily validates only during conversion.","solutions":["Read the wrapped error — plugins usually name the missing/invalid option","Fill in required storage module options (address, credentials, bucket, etc.) and re-validate the config","Rebuild with plugin versions matching your Caddy version (xcaddy build --with plugin@commit compatible with your Caddy release)","Test the storage module globally first (global storage option) to isolate CA-specific config issues"],"exampleFix":"# before\n\"pki\": { \"certificate_authorities\": { \"local\": {\n  \"storage\": { \"module\": \"redis\" }\n}}}\n\n# after\n\"pki\": { \"certificate_authorities\": { \"local\": {\n  \"storage\": { \"module\": \"redis\", \"address\": \"redis:6379\", \"password\": \"{env.REDIS_PASS}\" }\n}}}","handlingStrategy":"validation","validationCode":"// Exercise the module's conversion early with the same options:\nif sc, ok := loaded.(caddy.StorageConverter); ok {\n    if _, err := sc.CertMagicStorage(); err != nil {\n        return fmt.Errorf(\"storage module config invalid: %w\", err)\n    }\n}","typeGuard":"func isStorageConverter(v any) (caddy.StorageConverter, bool) {\n    sc, ok := v.(caddy.StorageConverter)\n    return sc, ok\n}","tryCatchPattern":"if err := ca.Provision(ctx, id, log); err != nil {\n    if strings.Contains(err.Error(), \"creating storage configuration\") {\n        return fmt.Errorf(\"check storage module options/credentials: %v\", err)\n    }\n}","preventionTips":["Pin plugin versions matched to your Caddy/certmagic version","Provide required storage options via env placeholders and fail deploy if envs are empty","Test custom storage globally before scoping it to a CA"],"tags":["pki","storage","modules","certmagic","config"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}