apache/kafka · error · ConfigException

Value must be non-null

Error message

Value must be non-null

What it means

Thrown by Range.ensureValid when the validated numeric value is null. Range is the built-in Validator used by ConfigDef.Range.atLeast / Range.between, applied to INT/LONG/SHORT/DOUBLE configs to enforce bounds. A null here means the value was not set and there is no default, so the validator refuses it rather than silently treating null as 0.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java:1010

        /**
         * A numeric range that checks only the lower bound
         *
         * @param min The minimum acceptable value
         */
        public static Range atLeast(Number min) {
            return new Range(min, null);
        }

        /**
         * A numeric range that checks both the upper (inclusive) and lower bound
         */
        public static Range between(Number min, Number max) {
            return new Range(min, max);
        }

        public void ensureValid(String name, Object o) {
            if (o == null)
                throw new ConfigException(name, null, "Value must be non-null");
            Number n = (Number) o;
            if (min != null && n.doubleValue() < min.doubleValue())
                throw new ConfigException(name, o, "Value must be at least " + min);
            if (max != null && n.doubleValue() > max.doubleValue())
                throw new ConfigException(name, o, "Value must be no more than " + max);
        }

        public String toString() {
            if (min == null && max == null)
                return "[...]";
            else if (min == null)
                return "[...," + max + "]";
            else if (max == null)
                return "[" + min + ",...]";
            else
                return "[" + min + ",...," + max + "]";
        }
    }

View on GitHub (pinned to c31c9215e1)

Solutions

  1. Provide an explicit non-null value for the property.
  2. Or define a sensible default in the ConfigDef entry (ConfigDef.Definition].defaultValue(…)).
  3. Filter out null entries before building the properties map (e.g. props.values().removeIf(Objects::isNull)).
  4. If the validator should permit null, use a different/combined Validator (e.g. a null-safe wrapper) or make the config optional at the schema level.

Example fix

// before
props.put(ConsumerConfig.FETCH_MIN_BYTES_CONFIG, null);
// -> ConfigException: Value must be non-null

// after
props.put(ConsumerConfig.FETCH_MIN_BYTES_CONFIG, 1);
// or omit it so the documented default applies
Defensive patterns

Strategy: validation

Validate before calling

if (value == null) {
    throw new IllegalArgumentException("config '" + key + "' must be a non-null number");
}

Type guard

public static boolean isNonNullNumber(Object v) {
    return v instanceof Number;
}

Try / catch

try {
    configDef.parse(configs);
} catch (ConfigException e) {
    if (e.getMessage().equals("Value must be non-null")) {
        // supply the documented default and retry
    } else throw e;
}

Prevention

When it happens

Trigger: A config key with a Range validator (e.g. num.network.threads, num.io.threads, request.timeout.ms with bounds, default.api.timeout.ms, fetch.max.bytes, max.partition.fetch.bytes) is omitted from the properties map AND has no default, or is explicitly set to null.

Common situations: Custom ConfigDef where a developer added a config with Range.atLeast(1) but forgot to supply a default; programmatic property assembly that puts null for missing keys; Spring @ConfigurationProperties binding a missing Optional as null and forwarding it; partial config objects merged where a key is later overwritten with null.

Related errors

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