{"record":{"id":"d4d4e2c2fcce98de","repo":"caddyserver/caddy","slug":"creating-tls-storage-configuration-v","errorCode":null,"errorMessage":"creating TLS storage configuration: %v","messagePattern":"creating TLS storage configuration: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddytls/automation.go","lineNumber":204,"sourceCode":"\tfor i, sub := range ap.SubjectsRaw {\n\t\tsub = repl.ReplaceAll(sub, \"\")\n\t\tsubASCII, err := idna.ToASCII(sub)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"could not convert automation policy subject '%s' to punycode: %v\", sub, err)\n\t\t}\n\t\tsubjects[i] = subASCII\n\t}\n\tap.subjects = subjects\n\n\t// policy-specific storage implementation\n\tif ap.StorageRaw != nil {\n\t\tval, err := tlsApp.ctx.LoadModule(ap, \"StorageRaw\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"loading TLS 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 TLS storage configuration: %v\", err)\n\t\t}\n\t\tap.storage = cmStorage\n\t}\n\n\t// we don't store loaded modules directly in the certmagic config since\n\t// policy provisioning may happen more than once (during auto-HTTPS) and\n\t// loading a module clears its config bytes; thus, load the module and\n\t// store them on the policy before putting it on the config\n\n\t// load and provision any cert manager modules\n\tif ap.ManagersRaw != nil {\n\t\tap.hadExplicitManagers = true\n\t\tvals, err := tlsApp.ctx.LoadModule(ap, \"ManagersRaw\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"loading external certificate manager modules: %v\", err)\n\t\t}\n\t\tfor _, getCertVal := range vals.([]any) {\n\t\t\tap.Managers = append(ap.Managers, getCertVal.(certmagic.Manager))","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddytls/automation.go#L186-L222","documentation":"The storage module loaded successfully but its CertMagicStorage() call (the caddy.StorageConverter interface) returned an error while constructing the underlying certmagic.Storage implementation. This is a failure inside the storage plugin itself — initializing a client, opening a database, checking a directory — not a module-loading problem.","triggerScenarios":"A StorageConverter module whose CertMagicStorage() fails: unable to reach Redis/Consul/S3 endpoints, invalid TLS certs for the storage backend, permission denied creating files under the storage root, bad DSN.","commonSituations":"Storage backend endpoint down or DNS not resolving at Caddy startup; file_system storage pointing at a root the caddy user cannot write; expired cloud credentials; firewall blocking the storage backend port.","solutions":["Fix the underlying cause reported by the wrapped error (connectivity, credentials, or filesystem permissions).","For file_system storage, ensure the root directory exists and is writable by the Caddy service user (mkdir -p && chown).","For network backends, verify the endpoint is reachable from the Caddy host (telnet/curl) and credentials are current.","Start Caddy only after the storage backend dependency is up, or use a systemd dependency ordering."],"exampleFix":"# before: root not writable\n\"storage\": {\"module\": \"file_system\", \"root\": \"/etc/caddy/storage\"}\n\n# after\nsudo mkdir -p /var/lib/caddy/storage && sudo chown caddy:caddy /var/lib/caddy/storage\n\"storage\": {\"module\": \"file_system\", \"root\": \"/var/lib/caddy/storage\"}","handlingStrategy":"validation","validationCode":"// For file_system storage: check writability up front.\ninfo, err := os.Stat(storageRoot)\nif err != nil || !info.IsDir() {\n    return fmt.Errorf(\"storage root %s missing\", storageRoot)\n}\nprobe := filepath.Join(storageRoot, \".probe\")\nif err := os.WriteFile(probe, nil, 0o600); err != nil {\n    return fmt.Errorf(\"storage root %s not writable: %v\", storageRoot, err)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pre-create and chown storage directories in provisioning tooling.","Order service startup so storage backends are up before Caddy (systemd After=/Requires=).","Monitor storage backend health and alert before renewal windows."],"tags":["tls","storage","permissions","network"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}