{"id":"dfe11875ce69ae3c","repo":"apache/kafka","slug":"zstd-doesn-t-support-given-compression-level-leve","errorCode":null,"errorMessage":"zstd doesn't support given compression level: level","messagePattern":"zstd doesn't support given compression level: level","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/compress/ZstdCompression.java","lineNumber":129,"sourceCode":"    @Override\n    public boolean equals(Object o) {\n        if (this == o) return true;\n        if (o == null || getClass() != o.getClass()) return false;\n        ZstdCompression that = (ZstdCompression) o;\n        return level == that.level;\n    }\n\n    @Override\n    public int hashCode() {\n        return Objects.hash(level);\n    }\n\n    public static class Builder implements Compression.Builder<ZstdCompression> {\n        private int level = ZSTD.defaultLevel();\n\n        public Builder level(int level) {\n            if (level < ZSTD.minLevel() || ZSTD.maxLevel() < level) {\n                throw new IllegalArgumentException(\"zstd doesn't support given compression level: \" + level);\n            }\n\n            this.level = level;\n            return this;\n        }\n\n        @Override\n        public ZstdCompression build() {\n            return new ZstdCompression(level);\n        }\n    }\n}\n","sourceCodeStart":111,"sourceCodeEnd":142,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/compress/ZstdCompression.java#L111-L142","documentation":"IllegalArgumentException thrown by ZstdCompression.Builder.level(int) when the requested zstd compression level is outside the supported range. Kafka pins zstd levels to the zstd library constants: minLevel=-131072 (ZSTD_minCLevel), maxLevel=22 (ZSTD_MAX_CLEVEL), defaultLevel=3. The guard is `level < -131072 || 22 < level`. Like the LZ4 check it fires at builder time, before any bytes are compressed.","triggerScenarios":"Calling Compression.of().zstd().level(n) (or setting producer config compression.zstd.level) with n > 22 or n < -131072. The upper bound (22) is by far the more common boundary to hit; the lower bound is effectively unreachable except by accident (e.g. a sign error or treating an unsigned config as signed).","commonSituations":"See trigger scenarios.","solutions":["Set the zstd level to a value in [-131072, 22]; the default is 3, levels 1-19 are standard, 20-22 require --ultra and a lot of memory.","If you do not need a specific level, omit .level() so the builder uses ZSTD.defaultLevel() (3).","If you need extreme compression, use 19 (or 20-22 cautiously); do not exceed 22.","Verify you are configuring the zstd codec and not accidentally applying an lz4/gzip level convention (which would under-use or over-shoot zstd's range)."],"exampleFix":"// before\nCompression compression = Compression.of().zstd().level(23).build(); // throws: 23 > 22\n\n// after\nCompression compression = Compression.of().zstd().level(3).build(); // valid; or omit .level() to use default 3","handlingStrategy":"validation","validationCode":"import org.apache.kafka.common.record.internal.CompressionType;\nint sanitizeZstdLevel(int requested) {\n    int lo = CompressionType.ZSTD.minLevel();\n    int hi = CompressionType.ZSTD.maxLevel();\n    if (requested < lo || requested > hi) {\n        return CompressionType.ZSTD.defaultLevel();\n    }\n    return requested;\n}\nCompression zstd = new ZstdCompression.Builder().level(sanitizeZstdLevel(userLevel)).build();","typeGuard":null,"tryCatchPattern":"try {\n    new ZstdCompression.Builder().level(userLevel).build();\n} catch (IllegalArgumentException e) {\n    // message starts with \"zstd doesn't support given compression level\"\n    log.warn(\"Invalid zstd level {}, falling back to default\", userLevel);\n    compression = Compression.zstd();\n}","preventionTips":["zstd's valid range is roughly 1..22, but query ZSTD.minLevel()/maxLevel() instead of assuming.","Higher zstd levels save bytes but cost CPU on both producer and consumer — pick deliberately.","Keep producer and consumer kafka-clients versions aligned so the level range is identical on both sides."],"tags":["compression","zstd","configuration","kafka-client","producer"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}