{"record":{"id":"aca3f3d10ca325d5","repo":"caddyserver/caddy","slug":"loading-external-certificate-manager-modules-v","errorCode":null,"errorMessage":"loading external certificate manager modules: %v","messagePattern":"loading external certificate manager modules: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddytls/automation.go","lineNumber":219,"sourceCode":"\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))\n\t\t}\n\t}\n\n\t// load and provision any explicitly-configured issuer modules\n\tif ap.IssuersRaw != nil {\n\t\tval, err := tlsApp.ctx.LoadModule(ap, \"IssuersRaw\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"loading TLS automation management module: %s\", err)\n\t\t}\n\t\tfor _, issVal := range val.([]any) {\n\t\t\tap.Issuers = append(ap.Issuers, issVal.(certmagic.Issuer))\n\t\t}\n\t}\n\n\tissuers := ap.Issuers","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddytls/automation.go#L201-L237","documentation":"The automation policy configures external certificate managers (managers, e.g. tls.get_certificate modules like Tailscale or a custom HTTPS-cert provider) and caddy.Context.LoadModule failed for one of them. The wrapped error is the module loader's or the module's Provision failure.","triggerScenarios":"Setting \"get_certificate\"/\"managers\" in a TLS automation policy to a module not built into the binary, or one whose Provision fails (bad endpoint URL, missing API key placeholder, invalid options).","commonSituations":"Using the Tailscale manager without the tailscale plugin compiled in; unset {$TS_AUTH_KEY} placeholders; wrong module JSON shape after upgrading Caddy where the managers API changed; typos in module names.","solutions":["Check the wrapped error to identify the failing manager module and its specific complaint.","Build Caddy with the required plugin (e.g. xcaddy build --with github.com/caddy-dns/... or the tailscale plugin) or remove the managers block.","Ensure all placeholders the manager depends on (API keys, URLs) are set in the environment.","Validate the manager's sub-config against the module's documentation for your Caddy version."],"exampleFix":"# before: manager plugin missing from binary\n{\n\tcert_issuer ... \n}\n# Caddyfile:\nexample.com {\n\ttls {\n\t\tget_certificate tailscale\n\t}\n}\n\n# after: custom build including the plugin\nxcaddy build --with github.com/caddyserver/caddy/v2/modules/caddytls/standard\n# (or remove the get_certificate block if the plugin is not needed)","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := policy.Provision(tlsApp); err != nil {\n    if strings.Contains(err.Error(), \"loading external certificate manager modules\") {\n        return fmt.Errorf(\"check get_certificate/managers config and plugins: %w\", err)\n    }\n}","preventionTips":["Ship the exact binary (xcaddy build with pinned plugins) that config validation ran against.","Set and verify all env placeholders managers rely on before deploy.","Validate configs in CI with the production build."],"tags":["tls","certificates","module-system","configuration"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}