caddyserver/caddy · error

getting module named '%s': %v

Error message

getting module named '%s': %v

What it means

`caddy file-server --precompressed X` startup error: no module with ID http.precompressed.X is registered. The module lookup fails because that precompression format is not compiled into the binary.

Source

Thrown at modules/caddyhttp/fileserver/command.go:139

			Prefer: []string{"zstd", "gzip"},
		}, "handler", "encode", nil))
	}

	if templates {
		handler := caddytpl.Templates{FileRoot: root}
		handlers = append(handlers, caddyconfig.JSONModuleObject(handler, "handler", "templates", nil))
	}

	handler := FileServer{Root: root}

	if len(precompressed) != 0 {
		// logic mirrors modules/caddyhttp/fileserver/caddyfile.go case "precompressed"
		var order []string
		for _, compression := range precompressed {
			modID := "http.precompressed." + compression
			mod, err := caddy.GetModule(modID)
			if err != nil {
				return caddy.ExitCodeFailedStartup, fmt.Errorf("getting module named '%s': %v", modID, err)
			}
			inst := mod.New()
			precompress, ok := inst.(encode.Precompressed)
			if !ok {
				return caddy.ExitCodeFailedStartup, fmt.Errorf("module %s is not a precompressor; is %T", modID, inst)
			}
			if handler.PrecompressedRaw == nil {
				handler.PrecompressedRaw = make(caddy.ModuleMap)
			}
			handler.PrecompressedRaw[compression] = caddyconfig.JSON(precompress, nil)
			order = append(order, compression)
		}
		handler.PrecompressedOrder = order
	}

	if browse {
		handler.Browse = &Browse{RevealSymlinks: revealSymlinks, FileLimit: fileLimit}
	}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Use only formats available in your build: check caddy list-modules | grep precompressed
2. Build with xcaddy adding the missing precompress module if one exists
3. Fix typos ('gzip' not 'gz', 'zstd' not 'zstandard')

Example fix

# before
caddy file-server --precompressed gz
# after
caddy file-server --precompressed gzip

# verify each requested format has a module
for f in gzip zstd; do caddy list-modules | grep -q "http.precompressed.$f" || echo "missing $f"; done

When it happens

Trigger: --precompressed br on a standard build without the brotli precompress module; any typo like --precompressed gz (valid names are gzip, zstd in standard builds).

Common situations: Expecting brotli precompression without building the plugin; misspelled format names in scripts.

Related errors

• invalid precompressed flag: %v
• module %s is not a precompressor; is %T
• loading encoder modules: %v
• module %s is not precompressor
• precompressor does not specify an Accept-Encoding value

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