caddyserver/caddy · error

loading external certificate manager modules: %v

Error message

loading external certificate manager modules: %v

What it means

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.

Source

Thrown at modules/caddytls/automation.go:219

		}
		cmStorage, err := val.(caddy.StorageConverter).CertMagicStorage()
		if err != nil {
			return fmt.Errorf("creating TLS storage configuration: %v", err)
		}
		ap.storage = cmStorage
	}

	// we don't store loaded modules directly in the certmagic config since
	// policy provisioning may happen more than once (during auto-HTTPS) and
	// loading a module clears its config bytes; thus, load the module and
	// store them on the policy before putting it on the config

	// load and provision any cert manager modules
	if ap.ManagersRaw != nil {
		ap.hadExplicitManagers = true
		vals, err := tlsApp.ctx.LoadModule(ap, "ManagersRaw")
		if err != nil {
			return fmt.Errorf("loading external certificate manager modules: %v", err)
		}
		for _, getCertVal := range vals.([]any) {
			ap.Managers = append(ap.Managers, getCertVal.(certmagic.Manager))
		}
	}

	// load and provision any explicitly-configured issuer modules
	if ap.IssuersRaw != nil {
		val, err := tlsApp.ctx.LoadModule(ap, "IssuersRaw")
		if err != nil {
			return fmt.Errorf("loading TLS automation management module: %s", err)
		}
		for _, issVal := range val.([]any) {
			ap.Issuers = append(ap.Issuers, issVal.(certmagic.Issuer))
		}
	}

	issuers := ap.Issuers

View on GitHub (pinned to 50e54ee279)

Solutions

1. Check the wrapped error to identify the failing manager module and its specific complaint.
2. Build Caddy with the required plugin (e.g. xcaddy build --with github.com/caddy-dns/... or the tailscale plugin) or remove the managers block.
3. Ensure all placeholders the manager depends on (API keys, URLs) are set in the environment.
4. Validate the manager's sub-config against the module's documentation for your Caddy version.

Example fix

# before: manager plugin missing from binary
{
	cert_issuer ... 
}
# Caddyfile:
example.com {
	tls {
		get_certificate tailscale
	}
}

# after: custom build including the plugin
xcaddy build --with github.com/caddyserver/caddy/v2/modules/caddytls/standard
# (or remove the get_certificate block if the plugin is not needed)

if err := policy.Provision(tlsApp); err != nil {
    if strings.Contains(err.Error(), "loading external certificate manager modules") {
        return fmt.Errorf("check get_certificate/managers config and plugins: %w", err)
    }
}

When it happens

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

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

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• loading TLS storage module: %v
• loading TLS automation management module: %s
• parsing certificate at index %d: %v
• URL is required
• no certificates matched custom selection policy

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