caddyserver/caddy · error

encoding %s not enabled

Error message

encoding %s not enabled

What it means

Validate-time error from the encode handler: a name listed in the 'prefer' array has no corresponding entry in enc.writerPools, i.e. that encoder was never registered in this encode block. Prefer can only reorder encodings that are actually enabled.

Source

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

	}

	if len(enc.Prefer) == 0 {
		for _, encName := range []string{"zstd", "br", "gzip"} {
			if _, ok := enc.writerPools[encName]; ok {
				enc.Prefer = append(enc.Prefer, encName)
			}
		}
	}

	return nil
}

// Validate ensures that enc's configuration is valid.
func (enc *Encode) Validate() error {
	check := make(map[string]bool)
	for _, encName := range enc.Prefer {
		if _, ok := enc.writerPools[encName]; !ok {
			return fmt.Errorf("encoding %s not enabled", encName)
		}

		if _, ok := check[encName]; ok {
			return fmt.Errorf("encoding %s is duplicated in prefer", encName)
		}
		check[encName] = true
	}

	return nil
}

func isEncodeAllowed(h http.Header) bool {
	return !strings.Contains(h.Get("Cache-Control"), "no-transform")
}

func (enc *Encode) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error {
	if isEncodeAllowed(r.Header) {
		for _, encName := range AcceptedEncodings(r, enc.Prefer) {

View on GitHub (pinned to 50e54ee279)

Solutions

1. Add the matching encoder to the encode config (e.g. "encodings": {"zstd": {}}) or use the Caddyfile 'encode zstd gzip' form
2. Ensure the encoder module exists in the build (caddy list-modules)
3. Fix typos in the prefer names — they must equal the encoder's Accept-Encoding token

Example fix

// before
{"handler": "encode", "prefer": ["zstd"]}
// after
{"handler": "encode", "encodings": {"zstd": {}, "gzip": {}}, "prefer": ["zstd"]}

# validate prefer entries are enabled encodings
caddy adapt --config Caddyfile --validate

When it happens

Trigger: {"encode": {"prefer": ["zstd"]}} without a zstd entry under "encodings" / no zstd module enabled; or preferring an encoder name that is misspelled.

Common situations: Assuming prefer implicitly enables an encoder; typo like 'br' vs 'brotli'; preferring an encoder not compiled into the custom build.

Related errors

• encoding %s is duplicated in prefer
• quality too low; must be >= %d
• quality too high; must be <= %d
• unexpected compression level, use one of '%s', '%s', '%s', '
• parsing listener address: %v

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