{"id":"71d7efe93f007a4b","repo":"apache/kafka","slug":"value-must-be-between-and-or-equal-to","errorCode":null,"errorMessage":"Value must be between {} and {} or equal to {}","messagePattern":"Value must be between (.+?) and (.+?) or equal to (.+?)","errorType":"validation","errorClass":"ConfigException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/record/internal/CompressionType.java","lineNumber":60,"sourceCode":"\n        @Override\n        public int maxLevel() {\n            return MAX_LEVEL;\n        }\n\n        @Override\n        public int minLevel() {\n            return MIN_LEVEL;\n        }\n\n        @Override\n        public ConfigDef.Validator levelValidator() {\n            return ConfigDef.LambdaValidator.with((name, value) -> {\n                if (value == null)\n                    throw new ConfigException(name, null, \"Value must be non-null\");\n                int level = ((Number) value).intValue();\n                if (level > MAX_LEVEL || (level < MIN_LEVEL && level != DEFAULT_LEVEL)) {\n                    throw new ConfigException(name, value, \"Value must be between \" + MIN_LEVEL + \" and \" + MAX_LEVEL + \" or equal to \" + DEFAULT_LEVEL);\n                }\n            }, () -> \"[\" + MIN_LEVEL + \",...,\" + MAX_LEVEL + \"] or \" + DEFAULT_LEVEL);\n        }\n    },\n\n    // We should only load classes from a given compression library when we actually use said compression library. This\n    // is because compression libraries include native code for a set of platforms and we want to avoid errors\n    // in case the platform is not supported and the compression library is not actually used.\n    // To ensure this, we only reference compression library code from classes that are only invoked when actual usage\n    // happens.\n    SNAPPY((byte) 2, \"snappy\", 1.0f),\n    LZ4((byte) 3, \"lz4\", 1.0f) {\n        // These values come from net.jpountz.lz4.LZ4Constants\n        // We may need to update them if the lz4 library changes these values.\n        private static final int MIN_LEVEL = 1;\n        private static final int MAX_LEVEL = 17;\n        private static final int DEFAULT_LEVEL = 9;\n","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/record/internal/CompressionType.java#L42-L78","documentation":"Thrown by the GZIP level validator when the supplied level is outside [MIN_LEVEL, MAX_LEVEL] AND is not equal to DEFAULT_LEVEL. Because java.util.zip.Deflater reserves -1 (DEFAULT_COMPRESSION) as a special sentinel distinct from the 1..9 numeric range, the validator allows exactly [1..9] or -1; any other int is rejected with ConfigException.","triggerScenarios":"Setting compression.type=gzip plus a compression.level value such as 0, 10, -2, 100, etc. — anything outside [Deflater.BEST_SPEED=1, Deflater.BEST_COMPRESSION=9] and not equal to Deflater.DEFAULT_COMPRESSION (-1).","commonSituations":"Operators coming from zstd/lz4 where the level scale differs (zstd allows negatives down to -131072 and up to 22; lz4 uses 1..17) and reusing the same numeric level for gzip. Typographical errors (e.g., level=99).","solutions":["Set gzip level to a value in [1..9] (higher = more CPU, smaller output) or -1 for Deflater's default.","If you copied a level from a zstd/lz4 config, translate it: zstd default 3 -> gzip default -1 or 6; lz4 default 9 -> gzip 6..9.","Validate the level at startup using ConfigDef.parse so the bad value fails fast instead of at runtime."],"exampleFix":"# before\ncompression.type=gzip\ncompression.level=22\n\n# after\ncompression.type=gzip\ncompression.level=6   # or -1 for DEFAULT_COMPRESSION","handlingStrategy":"validation","validationCode":"// GZIP levels: must be in [MIN_LEVEL, MAX_LEVEL] or equal DEFAULT_LEVEL\nint MIN = Deflater.BEST_SPEED;        // 1\nint MAX = Deflater.BEST_COMPRESSION;  // 9\nint DEFAULT = Deflater.DEFAULT_COMPRESSION; // -1\nif (level == null) throw new ConfigException(name, null, \"null\");\nif (!(level == DEFAULT || (level >= MIN && level <= MAX))) {\n    throw new ConfigException(name, level,\n        \"GZIP level must be in [\" + MIN + \",\" + MAX + \"] or \" + DEFAULT);\n}","typeGuard":"// Narrow a candidate GZIP level to the valid set\nstatic boolean isValidGzipLevel(int lvl) {\n    return lvl == Deflater.DEFAULT_COMPRESSION\n        || (lvl >= Deflater.BEST_SPEED && lvl <= Deflater.BEST_COMPRESSION);\n}","tryCatchPattern":"try {\n    type.levelValidator().ensureValid(\"compression.level\", level);\n} catch (org.apache.kafka.common.config.ConfigException e) {\n    // fall back to the codec's default level\n    level = type.defaultLevel();\n}","preventionTips":["Use type.defaultLevel() when in doubt rather than guessing a level.","GZIP only accepts Deflater levels 1-9 or -1; LZ4 uses 1-17, ZSTD uses -131072..22 — they are not interchangeable.","Run spotlessApply + checkstyle on config changes; misconfigured levels surface only at runtime."],"tags":["compression","gzip","configuration","config-exception"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}