apache/kafka · error · ConfigException

Value must be non-null

Error message

Value must be non-null

What it means

Thrown by the GZIP compression level validator inside CompressionType when the supplied config value is null. GZIP overrides levelValidator() to enforce the java.util.zip.Deflater level contract; a null level cannot be coerced to an int, so validation fails fast with ConfigException rather than NPE-ing later during compression.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/record/internal/CompressionType.java:57

        public int defaultLevel() {
            return DEFAULT_LEVEL;
        }

        @Override
        public int maxLevel() {
            return MAX_LEVEL;
        }

        @Override
        public int minLevel() {
            return MIN_LEVEL;
        }

        @Override
        public ConfigDef.Validator levelValidator() {
            return ConfigDef.LambdaValidator.with((name, value) -> {
                if (value == null)
                    throw new ConfigException(name, null, "Value must be non-null");
                int level = ((Number) value).intValue();
                if (level > MAX_LEVEL || (level < MIN_LEVEL && level != DEFAULT_LEVEL)) {
                    throw new ConfigException(name, value, "Value must be between " + MIN_LEVEL + " and " + MAX_LEVEL + " or equal to " + DEFAULT_LEVEL);
                }
            }, () -> "[" + MIN_LEVEL + ",...," + MAX_LEVEL + "] or " + DEFAULT_LEVEL);
        }
    },

    // We should only load classes from a given compression library when we actually use said compression library. This
    // is because compression libraries include native code for a set of platforms and we want to avoid errors
    // in case the platform is not supported and the compression library is not actually used.
    // To ensure this, we only reference compression library code from classes that are only invoked when actual usage
    // happens.
    SNAPPY((byte) 2, "snappy", 1.0f),
    LZ4((byte) 3, "lz4", 1.0f) {
        // These values come from net.jpountz.lz4.LZ4Constants
        // We may need to update them if the lz4 library changes these values.
        private static final int MIN_LEVEL = 1;

View on GitHub (pinned to c31c9215e1)

Solutions

1. Explicitly set the compression level property to a valid Deflater level (BEST_SPEED=1 .. BEST_COMPRESSION=9) or DEFAULT_COMPRESSION (-1).
2. Remove the explicit null/empty override so the validator falls back to the default level.
3. Verify the exact producer/broker config key name spelling against ConfigDef to ensure the value reaches the validator.

Example fix

// before
props.put(ProducerConfig.COMPRESSION_TYPE_CONFIG, "gzip");
props.put("compression.level", null);

// after
props.put(ProducerConfig.COMPRESSION_TYPE_CONFIG, "gzip");
props.put("compression.level", Deflater.DEFAULT_COMPRESSION);

// Before configuring a GZIP compression level:
if (level == null) {
    throw new IllegalArgumentException("compression.level must not be null");
}
// Then pass a non-null Integer/Number to the validator.

// Ensure the config value is a non-null Number before validation
static boolean isNonNullNumber(Object v) {
    return v instanceof Number;
}

try {
    compressionType.levelValidator().ensureValid(name, value);
} catch (org.apache.kafka.common.config.ConfigException e) {
    // value was null or invalid; supply a default level via defaultLevel()
}

When it happens

Trigger: Configuring compression.type=gzip together with a compression-level setting (e.g.,compression.level / producer config) whose value resolves to null — for example, an explicitly null producer property, an unset property dereferenced via ConfigDef.parse, or a config key typo that the validator receives as null.

Common situations: A properties file or env var override that sets compression.level to an empty/placeholder value parsed as null; a programmatic ProducerConfig map missing the key while GZIP is selected; misconfigured Connect worker using gzip with a null level.

Related errors

• Value must be between {} and {} or equal to {}
• Unknown compression name: {}
• Compression is not yet supported with the incremental buffer
• gzip doesn't support given compression level: level
• lz4 doesn't support given compression level: level

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