caddyserver/caddy · error

unexpected compression level, use one of '%s', '%s', '%s', '

Error message

unexpected compression level, use one of '%s', '%s', '%s', '%s'

What it means

parseEncoderLevel error from the zstd encoder: the Level string did not match any zstd.EncoderLevelFromString value. Acceptable names are the zstd speed constants printed in the message (fastest, better-compression, best-compression, default).

Source

Thrown at modules/caddyhttp/encode/zstd/zstd.go:155

}

func (z Zstd) encoderLevel() zstd.EncoderLevel {
	if z.level != 0 {
		return z.level
	}
	if z.Level != "" {
		if level, err := parseEncoderLevel(z.Level); err == nil {
			return level
		}
	}
	return zstd.SpeedDefault
}

func parseEncoderLevel(level string) (zstd.EncoderLevel, error) {
	if ok, encLevel := zstd.EncoderLevelFromString(level); ok {
		return encLevel, nil
	}
	return 0, fmt.Errorf("unexpected compression level, use one of '%s', '%s', '%s', '%s'",
		zstd.SpeedFastest,
		zstd.SpeedBetterCompression,
		zstd.SpeedBestCompression,
		zstd.SpeedDefault,
	)
}

// Interface guards
var (
	_ encode.Encoding       = (*Zstd)(nil)
	_ caddyfile.Unmarshaler = (*Zstd)(nil)
	_ caddy.Provisioner     = (*Zstd)(nil)
)

View on GitHub (pinned to 50e54ee279)

Solutions

1. Use one of: 'fastest', 'better-compression', 'best-compression', 'default'
2. Do not pass numbers for zstd; unlike gzip it takes named levels

Example fix

// before
{"level": "9"}
// after
{"level": "best-compression"}

var zstdLevels = map[string]bool{"fastest": true, "better-compression": true, "best-compression": true, "default": true}
if !zstdLevels[strings.ToLower(level)] { return errors.New("invalid zstd level") }

When it happens

Trigger: {"level": "max"} or "9" for the zstd encoder — anything not one of zstd.SpeedFastest / SpeedBetterCompression / SpeedBestCompression / SpeedDefault (case-insensitive per EncoderLevelFromString).

Common situations: Using gzip-style numeric levels as strings for zstd; assuming 'max'/'high' are valid names.

Related errors

• encoding %s not enabled
• encoding %s is duplicated in prefer
• quality too low; must be >= %d
• quality too high; must be <= %d
• parsing listener address: %v

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