apache/kafka · error · IllegalArgumentException

gzip doesn't support given compression level: level

Error message

gzip doesn't support given compression level: level

What it means

Thrown by GzipCompression.Builder.level(int) when the requested compression level is outside the bounds returned by CompressionType.GZIP.minLevel()/maxLevel() AND is not the default level. GZIP levels (1-9, JDK Deflater range) are bounded; passing 0, -1 (unless it equals defaultLevel()), 10, or any other out-of-range int is rejected with IllegalArgumentException at builder time rather than later during record compression.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/compress/GzipCompression.java:103

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        GzipCompression that = (GzipCompression) o;
        return level == that.level;
    }

    @Override
    public int hashCode() {
        return Objects.hash(level);
    }

    public static class Builder implements Compression.Builder<GzipCompression> {
        private int level = GZIP.defaultLevel();

        public Builder level(int level) {
            if ((level < GZIP.minLevel() || GZIP.maxLevel() < level) && level != GZIP.defaultLevel()) {
                throw new IllegalArgumentException("gzip doesn't support given compression level: " + level);
            }

            this.level = level;
            return this;
        }

        @Override
        public GzipCompression build() {
            return new GzipCompression(level);
        }
    }
}

View on GitHub (pinned to c31c9215e1)

Solutions

Use a level within [GZIP.minLevel(), GZIP.maxLevel()] (currently 1..9).
Omit the level() call entirely to accept the default, which is always allowed.
If you need 'use the default' explicitly, pass GZIP.defaultLevel() rather than guessing.
Validate external config values before forwarding them to the builder.

Example fix

// before
new GzipCompression.Builder().level(0).build();

// after
new GzipCompression.Builder().build(); // default level
// or
new GzipCompression.Builder().level(6).build(); // explicit valid level

Defensive patterns

Strategy: validation

Validate before calling

// GZIP.level accepts [minLevel..maxLevel] or exactly defaultLevel
int level = /* from config */;
if (level != GZIP.defaultLevel()
        && (level < GZIP.minLevel() || level > GZIP.maxLevel())) {
    // clamp or reject; do NOT forward to GzipCompression.Builder.level(level)
}

Try / catch

try {
    Compression gzip = new GzipCompression.Builder().level(level).build();
} catch (IllegalArgumentException e) {
    // "gzip doesn't support given compression level"; fall back to defaultLevel()
}

Prevention

Default to GZIP.defaultLevel(); only override when profiling justifies it.
If level comes from config/user input, clamp with min(max(level, minLevel()), maxLevel()) instead of passing it through.
Document the valid range next to the config key so operators do not guess (typically 1..9).
Treat an out-of-range level as a config error that fails deployment, not a runtime exception.

When it happens

Trigger: Calling `new GzipCompression.Builder().level(n)` with n < minLevel() (e.g. 0) or n > maxLevel() (e.g. 10 or 100). Typically reached when compression level comes from external config (producer.compression.gzip.level), a typo, or arithmetic that yields an out-of-range int.

Common situations: Misreading the gzip level range (assuming 0-9 or 1-12 like zstd); passing -1 expecting 'default' when defaultLevel() is a different value; config files with stale/wrong values copied from another codec's docs; dynamic config without validation.

Related errors

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/9e76c8261311bd90.json. Report an issue: GitHub.