{"record":{"id":"7ed90f537060e8c4","repo":"caddyserver/caddy","slug":"loading-overall-dns-provider-module-v","errorCode":null,"errorMessage":"loading overall DNS provider module: %v","messagePattern":"loading overall DNS provider module: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddytls/tls.go","lineNumber":181,"sourceCode":"\teventsAppIface, err := ctx.App(\"events\")\n\tif err != nil {\n\t\treturn fmt.Errorf(\"getting events app: %v\", err)\n\t}\n\tt.events = eventsAppIface.(*caddyevents.App)\n\tt.ctx = ctx\n\tt.logger = ctx.Logger()\n\trepl := caddy.NewReplacer()\n\tt.managing, t.loaded = make(map[string]string), make(map[string]string)\n\tt.serverNames = make(map[string]serverNameRegistration)\n\tt.serverNamesMu = new(sync.Mutex)\n\n\t// set up default DNS module, if any, and make sure it implements all the\n\t// common libdns interfaces, since it could be used for a variety of things\n\t// (do this before provisioning other modules, since they may rely on this)\n\tif len(t.DNSRaw) > 0 {\n\t\tdnsMod, err := ctx.LoadModule(t, \"DNSRaw\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"loading overall DNS provider module: %v\", err)\n\t\t}\n\t\tswitch dnsMod.(type) {\n\t\tcase interface {\n\t\t\tlibdns.RecordAppender\n\t\t\tlibdns.RecordDeleter\n\t\t\tlibdns.RecordGetter\n\t\t\tlibdns.RecordSetter\n\t\t}:\n\t\tdefault:\n\t\t\treturn fmt.Errorf(\"DNS module does not implement the most common libdns interfaces: %T\", dnsMod)\n\t\t}\n\t\tt.dns = dnsMod\n\t}\n\n\t// set up a new certificate cache; this (re)loads all certificates\n\tcacheOpts := certmagic.CacheOptions{\n\t\tGetConfigForCert: func(cert certmagic.Certificate) (*certmagic.Config, error) {\n\t\t\treturn t.getConfigForName(cert.Names[0]), nil","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddytls/tls.go#L163-L199","documentation":"Thrown during TLS app provisioning when the top-level 'dns' module (t.DNSRaw) cannot be loaded by ctx.LoadModule. This is Caddy's global DNS provider used by ACME DNS challenge and any other libdns-dependent feature. LoadModule fails when the module name in the raw JSON is not registered, the inline configuration fails the module's own Provision/Validate, or the JSON shape does not match the module's struct.","triggerScenarios":"Setting {\"dns\": {...}} in the tls app JSON (or the Caddyfile 'dns' global option) with an unknown module name, a typo like 'cloudflare' vs a non-existent plugin, or valid module name but invalid fields (e.g. missing API token). Also occurs if a custom build of Caddy was made without importing the module's package (not in modules/standard/imports.go).","commonSituations":"Using a DNS plugin (cloudflare, route53, etc.) that is not compiled into the downloaded Caddy binary (standard binaries exclude most DNS providers); wrong module key in JSON config; outdated plugin incompatible with the installed Caddy version after an upgrade.","solutions":["Verify the module is registered: run 'caddy list-modules' and confirm the DNS provider ID (e.g. 'dns.providers.cloudflare') appears","If missing, build Caddy with the plugin: 'xcaddy build --with github.com/caddy-dns/cloudflare'","Check the module name and fields in your config against the provider's docs (correct key, all required credentials present)","If using a plugin, make sure its version matches your Caddy core version (rebuild with xcaddy against the current tag)"],"exampleFix":"// before (binary without plugin)\n// caddy run --config Caddyfile  -> error: loading overall DNS provider module\n// Caddyfile: dns cloudflare {api_token ...}\n\n// after\n$ xcaddy build --with github.com/caddy-dns/cloudflare\n$ ./caddy list-modules | grep cloudflare\n$ ./caddy run --config Caddyfile","handlingStrategy":"validation","validationCode":"# before shipping: assert the module exists in the binary\ncaddy validate --config Caddyfile\ncaddy list-modules | grep -q 'dns.providers.cloudflare' || echo 'rebuild with xcaddy --with github.com/caddy-dns/cloudflare'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin both Caddy core and DNS plugin versions in your xcaddy build command","Run 'caddy validate' in CI for every config change","Keep a checked-in build script (xcaddy invocation) next to configs so the binary always includes required plugins"],"tags":["caddy","dns","module-loading","provisioning","tls"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}