caddyserver/caddy · error

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

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 is duplicated in prefer
• quality too high; must be <=
• quality too low; must be >=
• unexpected compression level, use one of
• automation policy is the second policy that acts as…

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

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