error decoding ECH metadata (%v) and cleaning up parent stor

Error message

error decoding ECH metadata (%v) and cleaning up parent storage key %s: %v

What it means

Error "error decoding ECH metadata (%v) and cleaning up parent storage key %s: %v" thrown in caddyserver/caddy.

Source

Thrown at modules/caddytls/ech.go:596

			zap.String("config_id", configID),
			zap.Error(err))
	} else if err != nil {
		delErr := storage.Delete(ctx, cfgIDKey)
		if delErr != nil {
			return echConfig{}, fmt.Errorf("error loading ECH config metadata (%v) and cleaning up parent storage key %s: %v", err, cfgIDKey, delErr)
		}
		logger.Warn("could not load ECH config metadata; deleted its folder",
			zap.String("config_id", configID),
			zap.Error(err))
		return echConfig{}, nil
	}
	var meta echConfigMeta
	if len(metaBytes) > 0 {
		if err := json.Unmarshal(metaBytes, &meta); err != nil {
			// even though it's just metadata, reset the whole config since we can't reliably maintain it
			delErr := storage.Delete(ctx, cfgIDKey)
			if delErr != nil {
				return echConfig{}, fmt.Errorf("error decoding ECH metadata (%v) and cleaning up parent storage key %s: %v", err, cfgIDKey, delErr)
			}
			logger.Warn("could not JSON-decode ECH metadata; deleted its config folder",
				zap.String("config_id", configID),
				zap.Error(err))
			return echConfig{}, nil
		}
	}

	cfg.privKeyBin = privKeyBytes
	cfg.configBin = echConfigBytes
	cfg.meta = meta

	return cfg, nil
}

func generateAndStoreECHConfig(ctx caddy.Context, publicName string) (echConfig, error) {
	// Go currently has very strict requirements for server-side ECH configs,
	// to quote the Go 1.24 godoc (with typos of AEAD IDs corrected):

View on GitHub (pinned to 50e54ee279)

Solutions

Inspect both wrapped errors: the ECH metadata failed to decode, and cleanup of its storage key also failed. Check storage health and data integrity.

When it happens

Trigger: Thrown at modules/caddytls/ech.go:596 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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