apache/kafka · error · ConfigException

Value must be no more than max

Error message

Value must be no more than max

What it means

Thrown by Range.ensureValid when a numeric value exceeds the upper bound declared via Range.between(min,max). It enforces a maximum acceptable value for bounded numeric configs (e.g. default.api.timeout.ms upper limit, fetch.max.partition.bytes ceiling, max.poll.interval.ms upper bound in some validators). The bound value is appended so the developer knows the ceiling.

Source

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

        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 {

        final ValidString validString;
        final boolean isEmptyAllowed;

View on GitHub (pinned to c31c9215e1)

Solutions

  1. Set the value to no more than the documented maximum (shown in the message).
  2. Double-check the documented unit (bytes vs KiB, ms vs seconds) — a unit mismatch is the usual cause of a too-large value.
  3. If you genuinely need more, check whether a different config (e.g. fetch.max.bytes vs max.message.bytes) is the correct knob.
  4. Upgrade or check KIP notes: ceilings are occasionally raised across versions.

Example fix

// before
props.put(ConsumerConfig.FETCH_MAX_BYTES_CONFIG,
         5_000_000_000L); // > Integer.MAX_VALUE-1
// -> ConfigException: Value must be no more than 2147483647

// after
props.put(ConsumerConfig.FETCH_MAX_BYTES_CONFIG,
         50 * 1024 * 1024); // 50 MiB
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

public static boolean meetsMax(Number value, Number max) {
    return value != null && max != null && value.doubleValue() <= max.doubleValue();
}

Try / catch

try {
    configDef.parse(configs);
} catch (ConfigException e) {
    if (e.getMessage().startsWith("Value must be no more than")) {
        // clamp down to `max` (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 above the documented maximum — e.g. fetch.max.bytes above Integer.MAX_VALUE-1, max.partition.fetch.bytes above the ceiling, a custom bounded config exceeded.

Common situations: Trying to lift a memory/size limit beyond what the broker protocol can carry (e.g. fetch.max.bytes above ~2GB); operator copy-paste from a tutorial that suggested an enormous value; unit confusion (passing bytes instead of KiB, or ms instead of seconds) producing a huge number; version migration where an upper bound was introduced.

Related errors

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