caddyserver/caddy · error

quality too high; must be <= %d

Error message

quality too high; must be <= %d

What it means

Validate-time error from the gzip encoder: Level exceeds gzip.BestCompression (9). Go's compress/gzip only accepts levels -2 through 9.

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)

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 >= %d
• encoding %s not enabled
• encoding %s is duplicated in prefer
• unexpected compression level, use one of '%s', '%s', '%s', '
• parsing listener address: %v

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