caddyserver/caddy · error

loading encoder modules: %v

Error message

loading encoder modules: %v

What it means

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.

Source

Thrown at modules/caddyhttp/encode/encode.go:74

	// The default is a collection of text-based Content-Type headers.
	Matcher *caddyhttp.ResponseMatcher `json:"match,omitempty"`

	writerPools map[string]*sync.Pool // TODO: these pools do not get reused through config reloads...
}

// CaddyModule returns the Caddy module information.
func (Encode) CaddyModule() caddy.ModuleInfo {
	return caddy.ModuleInfo{
		ID:  "http.handlers.encode",
		New: func() caddy.Module { return new(Encode) },
	}
}

// Provision provisions enc.
func (enc *Encode) Provision(ctx caddy.Context) error {
	mods, err := ctx.LoadModule(enc, "EncodingsRaw")
	if err != nil {
		return fmt.Errorf("loading encoder modules: %v", err)
	}
	for modName, modIface := range mods.(map[string]any) {
		err = enc.addEncoding(modIface.(Encoding))
		if err != nil {
			return fmt.Errorf("adding encoding %s: %v", modName, err)
		}
	}
	if enc.MinLength == 0 {
		enc.MinLength = defaultMinLength
	}

	if enc.Matcher == nil {
		// common text-based content types
		// list based on https://developers.cloudflare.com/speed/optimization/content/brotli/content-compression/#compression-between-cloudflare-and-website-visitors
		enc.Matcher = &caddyhttp.ResponseMatcher{
			Headers: http.Header{
				"Content-Type": []string{
					"application/atom+xml*",

View on GitHub (pinned to 50e54ee279)

Solutions

1. Check the wrapped error text for the exact module ID that failed
2. Verify the encoder module is compiled in: caddy list-modules | grep http.encodings
3. Rebuild with xcaddy including the missing plugin, or fix the typo in the encoding name
4. Ensure the encoding's inline JSON object matches the module's expected schema

Example fix

# before (build without brotli)
xcaddy build
# after
xcaddy build --with github.com/caddyserver/caddy/issues/none --with github.com/mholt/caddy-encode/brotli  # ensure plugin present

# before starting: confirm every encoder you reference exists
caddy list-modules | grep -E 'http.encodings.(zstd|gzip|br)'

When it happens

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

Common situations: Custom Caddy builds (xcaddy) missing an encoder plugin; typos in the encoding key; JSON config hand-edited with wrong inline module object.

Related errors

• --config is required
• adding encoding %s: %v
• loading storage module: %v
• creating storage value: %v
• loading listener wrapper modules: %v

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