{"record":{"id":"ac47b6d94107048a","repo":"caddyserver/caddy","slug":"loading-encoder-modules-v-ac47b6","errorCode":null,"errorMessage":"loading encoder modules: %v","messagePattern":"loading encoder modules: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/fileserver/staticfiles.go","lineNumber":224,"sourceCode":"\n\tif fsrv.IndexNames == nil {\n\t\tfsrv.IndexNames = defaultIndexNames\n\t}\n\n\t// for hide paths that are static (i.e. no placeholders), we can transform them into\n\t// absolute paths before the server starts for very slight performance improvement\n\tfor i, h := range fsrv.Hide {\n\t\tif !strings.Contains(h, \"{\") && strings.Contains(h, separator) {\n\t\t\tif abs, err := caddy.FastAbs(h); err == nil {\n\t\t\t\tfsrv.Hide[i] = abs\n\t\t\t}\n\t\t}\n\t}\n\n\t// support precompressed sidecar files\n\tmods, err := ctx.LoadModule(fsrv, \"PrecompressedRaw\")\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\tp, ok := modIface.(encode.Precompressed)\n\t\tif !ok {\n\t\t\treturn fmt.Errorf(\"module %s is not precompressor\", modName)\n\t\t}\n\t\tae := p.AcceptEncoding()\n\t\tif ae == \"\" {\n\t\t\treturn fmt.Errorf(\"precompressor does not specify an Accept-Encoding value\")\n\t\t}\n\t\tsuffix := p.Suffix()\n\t\tif suffix == \"\" {\n\t\t\treturn fmt.Errorf(\"precompressor does not specify a Suffix value\")\n\t\t}\n\t\tif _, ok := fsrv.precompressors[ae]; ok {\n\t\t\treturn fmt.Errorf(\"precompressor already added: %s\", ae)\n\t\t}\n\t\tif fsrv.precompressors == nil {","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/fileserver/staticfiles.go#L206-L242","documentation":"Returned during FileServer.Provision while loading the 'precompressed' configuration via ctx.LoadModule(fsrv, \"PrecompressedRaw\"). It means Caddy could not instantiate one of the configured precompression modules (the map under precompressed in JSON or the `precompressed` Caddyfile directive). The wrapped %v carries the underlying module-loading error, which names the real cause.","triggerScenarios":"Configuring `precompressed zstd gzip br` (or JSON \"precompressed\": {...}) with a module name that is misspelled, not compiled into the binary, or fails its own provisioning, causing LoadModule to return an error at config load/startup time.","commonSituations":"Using a custom build (xcaddy) that omits a precompressor module; typo in a module name in JSON config; upgrading Caddy where a precompressor module was renamed or removed; mixing JSON configs from a newer version against an older binary.","solutions":["Read the wrapped error (%v) — it identifies the exact module and underlying failure; fix that module name or its config.","Verify the module is present: `caddy list-modules | grep precompressed` and confirm the names you configured appear.","If using a custom build, rebuild with xcaddy including the module that provides the missing precompressor.","Remove the offending entry from the precompressed list to get the server running while you investigate."],"exampleFix":"# before\nprecompressed zstd gzip brotli\n# after (only encodings your binary supports)\nprecompressed zstd gzip","handlingStrategy":"validation","validationCode":"# CI step: fail before deploy if a configured precompressor is missing from the binary\nfor m in gzip zstd br; do\n  caddy list-modules | grep -q \"http.precompressed.$m\" || { echo \"missing precompressor: $m\"; exit 1; }\ndone\ncaddy validate --config Caddyfile","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `caddy validate --config <file>` in CI for every config change.","Pin and rebuild custom binaries with xcaddy from a lockfile listing required modules.","After Caddy upgrades, re-run `caddy list-modules` and diff against your config's module usage."],"tags":["caddy","fileserver","precompressed","provisioning","config"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}