{"record":{"id":"5264cb0be3443b9d","repo":"caddyserver/caddy","slug":"encoding-s-not-enabled","errorCode":null,"errorMessage":"encoding %s not enabled","messagePattern":"encoding (.+?) not enabled","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/encode/encode.go","lineNumber":148,"sourceCode":"\t}\n\n\tif len(enc.Prefer) == 0 {\n\t\tfor _, encName := range []string{\"zstd\", \"br\", \"gzip\"} {\n\t\t\tif _, ok := enc.writerPools[encName]; ok {\n\t\t\t\tenc.Prefer = append(enc.Prefer, encName)\n\t\t\t}\n\t\t}\n\t}\n\n\treturn nil\n}\n\n// Validate ensures that enc's configuration is valid.\nfunc (enc *Encode) Validate() error {\n\tcheck := make(map[string]bool)\n\tfor _, encName := range enc.Prefer {\n\t\tif _, ok := enc.writerPools[encName]; !ok {\n\t\t\treturn fmt.Errorf(\"encoding %s not enabled\", encName)\n\t\t}\n\n\t\tif _, ok := check[encName]; ok {\n\t\t\treturn fmt.Errorf(\"encoding %s is duplicated in prefer\", encName)\n\t\t}\n\t\tcheck[encName] = true\n\t}\n\n\treturn nil\n}\n\nfunc isEncodeAllowed(h http.Header) bool {\n\treturn !strings.Contains(h.Get(\"Cache-Control\"), \"no-transform\")\n}\n\nfunc (enc *Encode) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error {\n\tif isEncodeAllowed(r.Header) {\n\t\tfor _, encName := range AcceptedEncodings(r, enc.Prefer) {","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/encode/encode.go#L130-L166","documentation":"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.","triggerScenarios":"{\"encode\": {\"prefer\": [\"zstd\"]}} without a zstd entry under \"encodings\" / no zstd module enabled; or preferring an encoder name that is misspelled.","commonSituations":"Assuming prefer implicitly enables an encoder; typo like 'br' vs 'brotli'; preferring an encoder not compiled into the custom build.","solutions":["Add the matching encoder to the encode config (e.g. \"encodings\": {\"zstd\": {}}) or use the Caddyfile 'encode zstd gzip' form","Ensure the encoder module exists in the build (caddy list-modules)","Fix typos in the prefer names — they must equal the encoder's Accept-Encoding token"],"exampleFix":"// before\n{\"handler\": \"encode\", \"prefer\": [\"zstd\"]}\n// after\n{\"handler\": \"encode\", \"encodings\": {\"zstd\": {}, \"gzip\": {}}, \"prefer\": [\"zstd\"]}","handlingStrategy":"validation","validationCode":"# validate prefer entries are enabled encodings\ncaddy adapt --config Caddyfile --validate","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Every name in prefer must also appear in encodings","Prefer tokens equal the Accept-Encoding name (gzip, zstd, br)"],"tags":["caddy","encode","config","validation"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}