caddyserver/caddy · error

loading encoder modules: %v

Error message

loading encoder modules: %v

What it means

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.

Source

Thrown at modules/caddyhttp/fileserver/staticfiles.go:224

	if fsrv.IndexNames == nil {
		fsrv.IndexNames = defaultIndexNames
	}

	// for hide paths that are static (i.e. no placeholders), we can transform them into
	// absolute paths before the server starts for very slight performance improvement
	for i, h := range fsrv.Hide {
		if !strings.Contains(h, "{") && strings.Contains(h, separator) {
			if abs, err := caddy.FastAbs(h); err == nil {
				fsrv.Hide[i] = abs
			}
		}
	}

	// support precompressed sidecar files
	mods, err := ctx.LoadModule(fsrv, "PrecompressedRaw")
	if err != nil {
		return fmt.Errorf("loading encoder modules: %v", err)
	}
	for modName, modIface := range mods.(map[string]any) {
		p, ok := modIface.(encode.Precompressed)
		if !ok {
			return fmt.Errorf("module %s is not precompressor", modName)
		}
		ae := p.AcceptEncoding()
		if ae == "" {
			return fmt.Errorf("precompressor does not specify an Accept-Encoding value")
		}
		suffix := p.Suffix()
		if suffix == "" {
			return fmt.Errorf("precompressor does not specify a Suffix value")
		}
		if _, ok := fsrv.precompressors[ae]; ok {
			return fmt.Errorf("precompressor already added: %s", ae)
		}
		if fsrv.precompressors == nil {

View on GitHub (pinned to 50e54ee279)

Solutions

1. Read the wrapped error (%v) — it identifies the exact module and underlying failure; fix that module name or its config.
2. Verify the module is present: `caddy list-modules | grep precompressed` and confirm the names you configured appear.
3. If using a custom build, rebuild with xcaddy including the module that provides the missing precompressor.
4. Remove the offending entry from the precompressed list to get the server running while you investigate.

Example fix

# before
precompressed zstd gzip brotli
# after (only encodings your binary supports)
precompressed zstd gzip

# CI step: fail before deploy if a configured precompressor is missing from the binary
for m in gzip zstd br; do
  caddy list-modules | grep -q "http.precompressed.$m" || { echo "missing precompressor: $m"; exit 1; }
done
caddy validate --config Caddyfile

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• precompressor already added: %s
• loading new config: %v
• loading storage module: %v
• server %s: %v
• server %s: setting up route handlers: %v

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