caddyserver/caddy · error

--config is required

Error message

--config is required

What it means

During ECH Provision, Caddy failed to instantiate the configured publication modules (PublishersRaw) for an entry in the tls.encrypted_client_hello publication list. ctx.LoadModule resolves each embedded publisher module (e.g. DNS provider modules) from the JSON config, and that resolution or construction failed.

Solutions

1. Check the wrapped error for the exact module name that failed to load.
2. If a DNS publisher is configured, build Caddy with the matching DNS provider module (xcaddy build with the plugin, or use a build containing it).
3. Correct the module name/namespace in the tls { ech { publication } } config.
4. Verify plugin and Caddy versions are compatible after upgrades.

Example fix

# before: config references a publisher whose plugin is absent
xcaddy build
# caddy errors: loading ECH publication modules: ...

# after: include the DNS provider module
xcaddy build --with github.com/caddy-dns/cloudflare

// Before deploying, confirm required modules are present in the build:
// caddy list-modules | grep <publisher-module-id>
// Or validate config against the running binary:
// caddy validate --config Caddyfile

Treat as fatal config error: run `caddy validate --config Caddyfile` in CI to catch missing modules before deploy; the wrapped error names the module that failed.

When it happens

Trigger: An ech.publication entry references a module name that is not registered in the build (e.g. a DNS provider not compiled in), or the module's own provisioning failed (bad provider credentials shape, unknown fields).

Common situations: Using a Caddy build without the required DNS provider plugin (custom builds via xcaddy); typos in the module name in the JSON config or Caddyfile adaptation; version drift where a plugin changed its module ID.

Related errors

• the 'forwarded' option is no longer supported; use the…
• cannot reuse socket : unix socket is already in use by…
• ErrInvalidSplitPath
• --input is required
• loading encoder modules

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

Appendix: source

Thrown at cmd/storagefuncs.go:69

	err = json.Unmarshal(cfg, &tmpStruct)
	if err != nil {
		// default case, ignore the error
		var jsonError *json.SyntaxError
		if errors.As(err, &jsonError) {
			return nil, nil
		}
		return nil, err
	}

	return &tmpStruct, nil
}

func cmdImportStorage(fl Flags) (int, error) {
	importStorageCmdConfigFlag := fl.String("config")
	importStorageCmdImportFile := fl.String("input")

	if importStorageCmdConfigFlag == "" {
		return caddy.ExitCodeFailedStartup, errors.New("--config is required")
	}
	if importStorageCmdImportFile == "" {
		return caddy.ExitCodeFailedStartup, errors.New("--input is required")
	}

	// extract storage from config if possible
	storageCfg, err := determineStorage(importStorageCmdConfigFlag, "")
	if err != nil {
		return caddy.ExitCodeFailedStartup, err
	}

	// load specified storage or fallback to default
	var stor certmagic.Storage
	ctx, cancel := caddy.NewContext(caddy.Context{Context: context.Background()})
	defer cancel()
	if storageCfg != nil && storageCfg.StorageRaw != nil {
		val, err := ctx.LoadModule(storageCfg, "StorageRaw")
		if err != nil {

View on GitHub (pinned to 50e54ee279)