caddyserver/caddy · error

quality too high; must be <=

Error message

quality too high; must be <= %d

What it means

Raised by Gzip.Validate when the configured compression quality (g.Level) exceeds gzip.BestCompression (9), the maximum level supported by Go's compress/gzip. It is a configuration validation guard: the user-set quality value is out of the compiler's allowable range on the high end, so Caddy rejects the config before the encoder is ever used.

Solutions

1. Set level to at most 9; typical values are 5-9
2. Omit level to accept the default (defaultGzipLevel)

Example fix

// before
{"level": 11}
// after
{"level": 9}

if lvl > 9 { lvl = 9 } // clamp, or reject in config validation

When it happens

Trigger: {"level": 10} or higher in the gzip encoder config — often carried over from brotli (0-11) or zstd conventions.

Common situations: Porting compression settings from nginx (gzip levels up to 9 are fine but brotli configs use 11) or other servers with wider ranges.

Related errors

• quality too low; must be >=
• encoding is duplicated in prefer
• encoding not enabled
• unexpected compression level, use one of
• automation policy is the second policy that acts as…

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

Appendix: source

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

	g.Level = level
	return nil
}

// Provision provisions g's configuration.
func (g *Gzip) Provision(ctx caddy.Context) error {
	if g.Level == 0 {
		g.Level = defaultGzipLevel
	}
	return nil
}

// Validate validates g's configuration.
func (g Gzip) Validate() error {
	if g.Level < gzip.StatelessCompression {
		return fmt.Errorf("quality too low; must be >= %d", gzip.StatelessCompression)
	}
	if g.Level > gzip.BestCompression {
		return fmt.Errorf("quality too high; must be <= %d", gzip.BestCompression)
	}
	return nil
}

// AcceptEncoding returns the name of the encoding as
// used in the Accept-Encoding request headers.
func (Gzip) AcceptEncoding() string { return "gzip" }

// NewEncoder returns a new gzip writer.
func (g Gzip) NewEncoder() encode.Encoder {
	writer, _ := gzip.NewWriterLevel(nil, g.Level)
	return writer
}

// Informed from http://blog.klauspost.com/gzip-performance-for-go-webservers/
var defaultGzipLevel = 5

// Interface guards

View on GitHub (pinned to 50e54ee279)