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.

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)

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 'clie
• --input is required
• --output is required
• cannot reuse socket %v: unix socket is already in use by ano
• missing 'req' argument

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