caddyserver/caddy · error

adding encoding

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).

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

• encoder already added
• encoder does not specify an Accept-Encoding value
• loading encoder modules
• command already registered
• command short string is required

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

Appendix: 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)