flate: invalid compression level %d: want value in range [-2

Error message

flate: invalid compression level %d: want value in range [-2, 9]

What it means

The `compress/flate` package's `compressor` setup accepts only levels in the inclusive range [-2, 9]: HuffmanOnly(-2), through BestCompression(9), plus the constant aliases. A level outside that range hits the `default` case and the function returns this error. The same range is enforced for both `flate` and the underlying DEFLATE writer.

Source

Thrown at src/compress/flate/deflate.go:748

		d.step = (*compressor).deflateHuff
	case level == DefaultCompression:
		level = 6
		fallthrough
	case 1 <= level && level <= 6:
		d.w.logNewTablePenalty = 7
		d.fast = newFastEnc(level)
		d.window = make([]byte, maxStoreBlockSize)
		d.fill = (*compressor).fillBlock
		d.step = (*compressor).deflateFast
	case 7 <= level && level <= 9:
		d.w.logNewTablePenalty = 8
		d.state = &advancedState{}
		d.compressionLevel = levels[level]
		d.initDeflate()
		d.fill = (*compressor).fillDeflate
		d.step = (*compressor).deflateLazy
	default:
		return fmt.Errorf("flate: invalid compression level %d: want value in range [-2, 9]", level)
	}
	d.level = level
	return nil
}

// reset resets the compressor with a new output writer.
func (d *compressor) reset(w io.Writer) {
	d.w.reset(w)
	d.sync = false
	d.err = nil
	d.windowEnd = 0
	// We only need to reset a few things for fast encoders.
	if d.fast != nil {
		d.fast.reset()
		d.tokens.Reset()
		return
	}
	if d.compressionLevel.chain == 0 {

View on GitHub (pinned to b6b368adc5)

Solutions

Clamp the level to the valid range: `if level < flate.HuffmanOnly { level = flate.HuffmanOnly } else if level > flate.BestCompression { level = flate.BestCompression }`.
Use the package constants (`flate.DefaultCompression`, `flate.BestSpeed`, `flate.BestCompression`, `flate.HuffmanOnly`) instead of literals.
Map a `Compression` enum from your config to one of the constants before passing it in.

Example fix

// before
w, err := flate.NewWriter(out, 11)
// after
level := 11
if level > flate.BestCompression {
    level = flate.BestCompression
}
w, err := flate.NewWriter(out, level)

Defensive patterns

Strategy: validation

Validate before calling

if level < flate.HuffmanOnly || level > flate.BestCompression {
    level = flate.DefaultCompression
}

Try / catch

w, err := flate.NewWriter(out, level)
if err != nil { /* level invalid — clamp and retry */ }

Prevention

Always use flate's named level constants rather than raw integers.
Validate user-supplied compression levels at config-load time.

When it happens

Trigger: Calling `flate.NewWriter(w, level)` / `reset`-ing a compressor with level 10, -3, 11, or any int outside [-2,9]; passing a user-config value (e.g. from YAML) without clamping; arithmetic that produces e.g. `level = max+1`.

Common situations: Config file lets a user set `level: 11`; defaulting a numeric level from an env var that defaults to 0 or a sentinel interpreted as a real level; mixing up gzip/flate/zlib level ranges (they share the same -2..9, but callers sometimes pass 1..12).

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/bb0157f9c3905dc5. Report an issue: GitHub.