{"record":{"id":"e544f1acceef86a6","repo":"caddyserver/caddy","slug":"loading-encoder-modules-v","errorCode":null,"errorMessage":"loading encoder modules: %v","messagePattern":"loading encoder modules: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/encode/encode.go","lineNumber":74,"sourceCode":"\t// The default is a collection of text-based Content-Type headers.\n\tMatcher *caddyhttp.ResponseMatcher `json:\"match,omitempty\"`\n\n\twriterPools map[string]*sync.Pool // TODO: these pools do not get reused through config reloads...\n}\n\n// CaddyModule returns the Caddy module information.\nfunc (Encode) CaddyModule() caddy.ModuleInfo {\n\treturn caddy.ModuleInfo{\n\t\tID:  \"http.handlers.encode\",\n\t\tNew: func() caddy.Module { return new(Encode) },\n\t}\n}\n\n// Provision provisions enc.\nfunc (enc *Encode) Provision(ctx caddy.Context) error {\n\tmods, err := ctx.LoadModule(enc, \"EncodingsRaw\")\n\tif err != nil {\n\t\treturn fmt.Errorf(\"loading encoder modules: %v\", err)\n\t}\n\tfor modName, modIface := range mods.(map[string]any) {\n\t\terr = enc.addEncoding(modIface.(Encoding))\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"adding encoding %s: %v\", modName, err)\n\t\t}\n\t}\n\tif enc.MinLength == 0 {\n\t\tenc.MinLength = defaultMinLength\n\t}\n\n\tif enc.Matcher == nil {\n\t\t// common text-based content types\n\t\t// list based on https://developers.cloudflare.com/speed/optimization/content/brotli/content-compression/#compression-between-cloudflare-and-website-visitors\n\t\tenc.Matcher = &caddyhttp.ResponseMatcher{\n\t\t\tHeaders: http.Header{\n\t\t\t\t\"Content-Type\": []string{\n\t\t\t\t\t\"application/atom+xml*\",","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/encode/encode.go#L56-L92","documentation":"Provision-time error from the encode handler when caddy.Context.LoadModule fails to instantiate the configured encoder modules (EncodingsRaw). The wrapped error usually says which module ID failed to load or why unmarshaling failed.","triggerScenarios":"Configuring encode with an encoding module name that is not registered, e.g. {\"encode\": {\"encodings\": {\"brotli\": {}}}} in a build where the brotli module was not compiled in; or a malformed module JSON body.","commonSituations":"Custom Caddy builds (xcaddy) missing an encoder plugin; typos in the encoding key; JSON config hand-edited with wrong inline module object.","solutions":["Check the wrapped error text for the exact module ID that failed","Verify the encoder module is compiled in: caddy list-modules | grep http.encodings","Rebuild with xcaddy including the missing plugin, or fix the typo in the encoding name","Ensure the encoding's inline JSON object matches the module's expected schema"],"exampleFix":"# before (build without brotli)\nxcaddy build\n# after\nxcaddy build --with github.com/caddyserver/caddy/issues/none --with github.com/mholt/caddy-encode/brotli  # ensure plugin present","handlingStrategy":"validation","validationCode":"# before starting: confirm every encoder you reference exists\ncaddy list-modules | grep -E 'http.encodings.(zstd|gzip|br)'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Build with xcaddy and list modules in CI to pin the expected encoder set","Adapt and validate configs against the same binary that will serve them"],"tags":["caddy","encode","modules","provision","xcaddy"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}