caddyserver/caddy · error

provisioning Encrypted ClientHello components: %v

Error message

provisioning Encrypted ClientHello components: %v

What it means

When tls.encrypted_client_hello is configured, its Provision loads the ECH key sources and computes the outer names to be used in ECHConfig advertisements. This error wraps any failure in that setup: unparseable ECH keys (ECHConfigList PEM), missing/unloadable DNS provider required to publish ECH configs, or invalid ECH parameters.

Source

Thrown at modules/caddytls/tls.go:348

		if err := perm.Provision(ctx); err != nil {
			return fmt.Errorf("provisioning 'ask' module: %v", err)
		}
		t.Automation.OnDemand.permission = perm
	}

	// session ticket ephemeral keys (STEK) service and provider
	if t.SessionTickets != nil {
		err := t.SessionTickets.provision(ctx)
		if err != nil {
			return fmt.Errorf("provisioning session tickets configuration: %v", err)
		}
	}

	// ECH (Encrypted ClientHello) initialization
	if t.EncryptedClientHello != nil {
		outerNames, err := t.EncryptedClientHello.Provision(ctx)
		if err != nil {
			return fmt.Errorf("provisioning Encrypted ClientHello components: %v", err)
		}

		// outer names should have certificates to reduce client brittleness
		for _, outerName := range outerNames {
			if outerName == "" {
				continue
			}
			if !t.HasCertificateForSubject(outerName) {
				if t.automateNames == nil {
					t.automateNames = make(map[string]struct{})
				}
				t.automateNames[outerName] = struct{}{}
			}
		}
	}

	return nil
}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Read the wrapped error — it names whether keys parsing or DNS provider loading failed
2. Regenerate the ECH key set with a tool/version matching your Caddy build (ECH draft versions must align)
3. If advertising via DNS, ensure a working tls.dns provider is configured
4. Test with 'caddy validate' and consult the ECH docs section for current key generation commands

openssl pkeyutl ... # or simply:
test -s ech_keys.pem && grep -q 'BEGIN ECHCONFIG' ech_keys.pem || echo 'invalid ECH key file'

When it happens

Trigger: Configuring encrypted_client_hello with a keys PEM that is not a valid ECHConfigList; specifying a DNS provider for ECH publication that fails to load; building keys with incompatible draft versions than the runtime expects.

Common situations: Early adopters of ECH generating keys with mismatched OpenSSL/Cloudflare tooling; forgetting the dns provider needed for DNS-HTTPS-record publication; draft version drift between Caddy releases.

Related errors

• --config is required
• the 'forwarded' option is no longer supported; use the 'clie
• loading ECH DNS provider module: %v
• ECH DNS provider module is not an ECH DNS Provider: %v
• could not determine zone for domain: %w (domain=%s nameserve

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