apache/kafka · error · ConfigException

Value must be at least min

Error message

Value must be at least min

What it means

Thrown by Range.ensureValid when a numeric value is below the lower bound declared via Range.atLeast(min) or Range.between(min,max). This enforces a minimum acceptable value for bounded numeric configs (e.g. reconnect.backoff.ms >= 0, request.timeout.ms >= 1, num.io.threads >= 1, fetch.max.bytes >= 1). The bound value is appended to the message so the developer knows the threshold.

Source

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

         * @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 + "]";
        }
    }

    public static class ValidList implements Validator {

View on GitHub (pinned to c31c9215e1)

Solutions

  1. Set the value to at least the documented minimum (shown in the message).
  2. If you intended to disable the behavior, find the documented 'disable' value (often 0 or Long.MAX_VALUE) rather than a negative number.
  3. Check the Kafka docs for the specific version — bounds can change across releases.
  4. Re-validate the full ConfigDef via AdminClient.describeConfigs or ConfigDef.validate to surface any other out-of-range keys at once.

Example fix

// before
props.put(ProducerConfig.RETRIES_CONFIG, -1);
// -> ConfigException: Value must be at least 0

// after
props.put(ProducerConfig.RETRIES_CONFIG, Integer.MAX_VALUE); // or 0
Defensive patterns

Strategy: validation

Validate before calling

if (value instanceof Number) {
    double n = ((Number) value).doubleValue();
    if (min != null && n < min.doubleValue()) {
        throw new IllegalArgumentException("config '" + key + "' must be >= " + min);
    }
}

Type guard

public static boolean meetsMin(Number value, Number min) {
    return value != null && min != null && value.doubleValue() >= min.doubleValue();
}

Try / catch

try {
    configDef.parse(configs);
} catch (ConfigException e) {
    if (e.getMessage().startsWith("Value must be at least")) {
        // clamp up to `min` (or surface to the operator) and retry
    } else throw e;
}

Prevention

When it happens

Trigger: Calling ConfigDef.validate or constructing a client with a numeric config set below the documented minimum — e.g. retries=-1, request.timeout.ms=0, fetch.min.bytes=-5, num.network.threads=0, max.poll.records=0.

Common situations: Operator tuning a broker/client below the safe minimum to disable a feature (e.g. setting a timeout to 0 expecting 'disabled'); negative values used as 'infinite' sentinels; config templating that subtracts from a base; copy-paste from a stale doc with different bounds; migration between Kafka versions where the lower bound was tightened.

Related errors

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