caddyserver/caddy · error

adding encoding %s: %v

Error message

adding encoding %s: %v

What it means

Provision-time error when addEncoding() rejects a successfully-loaded encoder module. It wraps either 'encoder does not specify an Accept-Encoding value' (empty AcceptEncoding()) or 'encoder already added: %s' (two encoders claiming the same Accept-Encoding token).

Source

Thrown at modules/caddyhttp/encode/encode.go:79

// CaddyModule returns the Caddy module information.
func (Encode) CaddyModule() caddy.ModuleInfo {
	return caddy.ModuleInfo{
		ID:  "http.handlers.encode",
		New: func() caddy.Module { return new(Encode) },
	}
}

// Provision provisions enc.
func (enc *Encode) Provision(ctx caddy.Context) error {
	mods, err := ctx.LoadModule(enc, "EncodingsRaw")
	if err != nil {
		return fmt.Errorf("loading encoder modules: %v", err)
	}
	for modName, modIface := range mods.(map[string]any) {
		err = enc.addEncoding(modIface.(Encoding))
		if err != nil {
			return fmt.Errorf("adding encoding %s: %v", modName, err)
		}
	}
	if enc.MinLength == 0 {
		enc.MinLength = defaultMinLength
	}

	if enc.Matcher == nil {
		// common text-based content types
		// list based on https://developers.cloudflare.com/speed/optimization/content/brotli/content-compression/#compression-between-cloudflare-and-website-visitors
		enc.Matcher = &caddyhttp.ResponseMatcher{
			Headers: http.Header{
				"Content-Type": []string{
					"application/atom+xml*",
					"application/eot*",
					"application/font*",
					"application/geo+json*",
					"application/graphql+json*",
					"application/graphql-response+json*",

View on GitHub (pinned to 50e54ee279)

Solutions

1. Read the wrapped error to see which encoding name collided or was empty
2. Remove the duplicate encoder from the encode block
3. If authoring a plugin, return a unique non-empty string from AcceptEncoding()

Example fix

// before (plugin)
func (MyEnc) AcceptEncoding() string { return "" }
// after
func (MyEnc) AcceptEncoding() string { return "myenc" }

// For plugin authors: interface guard so AcceptEncoding contract is explicit
var _ encode.Encoding = (*MyEncoder)(nil)

When it happens

Trigger: Two encoder modules in the same encode block returning the same AcceptEncoding() string, or a third-party encoder whose AcceptEncoding() returns "".

Common situations: Installing a custom encoder plugin that duplicates gzip/zstd's encoding name; writing your own Encoding implementation and forgetting AcceptEncoding().

Related errors

• loading encoder modules: %v
• encoder does not specify an Accept-Encoding value
• encoder already added: %s
• --config is required
• loading storage module: %v

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