caddyserver/caddy · error

loading overall DNS provider module: %v

Error message

loading overall DNS provider module: %v

What it means

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.

Source

Thrown at modules/caddytls/tls.go:181

	eventsAppIface, err := ctx.App("events")
	if err != nil {
		return fmt.Errorf("getting events app: %v", err)
	}
	t.events = eventsAppIface.(*caddyevents.App)
	t.ctx = ctx
	t.logger = ctx.Logger()
	repl := caddy.NewReplacer()
	t.managing, t.loaded = make(map[string]string), make(map[string]string)
	t.serverNames = make(map[string]serverNameRegistration)
	t.serverNamesMu = new(sync.Mutex)

	// set up default DNS module, if any, and make sure it implements all the
	// common libdns interfaces, since it could be used for a variety of things
	// (do this before provisioning other modules, since they may rely on this)
	if len(t.DNSRaw) > 0 {
		dnsMod, err := ctx.LoadModule(t, "DNSRaw")
		if err != nil {
			return fmt.Errorf("loading overall DNS provider module: %v", err)
		}
		switch dnsMod.(type) {
		case interface {
			libdns.RecordAppender
			libdns.RecordDeleter
			libdns.RecordGetter
			libdns.RecordSetter
		}:
		default:
			return fmt.Errorf("DNS module does not implement the most common libdns interfaces: %T", dnsMod)
		}
		t.dns = dnsMod
	}

	// set up a new certificate cache; this (re)loads all certificates
	cacheOpts := certmagic.CacheOptions{
		GetConfigForCert: func(cert certmagic.Certificate) (*certmagic.Config, error) {
			return t.getConfigForName(cert.Names[0]), nil

View on GitHub (pinned to 50e54ee279)

Solutions

1. Verify the module is registered: run 'caddy list-modules' and confirm the DNS provider ID (e.g. 'dns.providers.cloudflare') appears
2. If missing, build Caddy with the plugin: 'xcaddy build --with github.com/caddy-dns/cloudflare'
3. Check the module name and fields in your config against the provider's docs (correct key, all required credentials present)
4. If using a plugin, make sure its version matches your Caddy core version (rebuild with xcaddy against the current tag)

Example fix

// before (binary without plugin)
// caddy run --config Caddyfile  -> error: loading overall DNS provider module
// Caddyfile: dns cloudflare {api_token ...}

// after
$ xcaddy build --with github.com/caddy-dns/cloudflare
$ ./caddy list-modules | grep cloudflare
$ ./caddy run --config Caddyfile

# before shipping: assert the module exists in the binary
caddy validate --config Caddyfile
caddy list-modules | grep -q 'dns.providers.cloudflare' || echo 'rebuild with xcaddy --with github.com/caddy-dns/cloudflare'

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• loading certificate loader modules: %s
• loading on-demand TLS permission module: %v
• provisioning default public automation policy: %v
• provisioning automation policy %d: %v
• provisioning session tickets configuration: %v

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/7ed90f537060e8c4. Report an issue: GitHub.