apache/kafka · error · ConfigException

exceeds maximum list size of [maxSize].

Error message

exceeds maximum list size of [maxSize].

What it means

Thrown by the ConfigDef.ListSize validator (an inner Validator of ConfigDef) when a list-typed config value has more entries than the configured maximum. The validator is instantiated via ListSize.atMostOfSize(maxSize) and ensureValid() compares values.size() against maxSize, throwing ConfigException(name, value, ...) with the bound in the message. Kafka uses this to cap list-valued configs (e.g. broker/client lists) so configuration parsing fails fast before runtime use.

Source

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

    }

    public static class ListSize implements Validator {
        final int maxSize;

        private ListSize(final int maxSize) {
            this.maxSize = maxSize;
        }

        public static ListSize atMostOfSize(final int maxSize) {
            return new ListSize(maxSize);
        }

        @Override
        public void ensureValid(final String name, final Object value) {
            @SuppressWarnings("unchecked")
            List<String> values = (List<String>) value;
            if (values.size() > maxSize) {
                throw new ConfigException(name, value, "exceeds maximum list size of [" + maxSize + "].");
            }
        }

        @Override
        public String toString() {
            return "List containing maximum of " + maxSize + " elements";
        }
    }

    public static class ConfigKey {
        public final String name;
        public final Type type;
        public final String documentation;
        public final Object defaultValue;
        public final Validator validator;
        public final Importance importance;
        public final String group;
        public final int orderInGroup;

View on GitHub (pinned to c31c9215e1)

Solutions

1. Count entries of the offending config value and trim the list to at most maxSize (the number shown in the message).
2. Find the config key in ConfigDef by searching for ListSize.atMostOfSize(...) usage and confirm the documented maximum for that property.
3. If the higher count is genuinely required, raise the cap in the ConfigDef definition (requires source change) or split workload across multiple config keys.

Example fix

// before
props.put("my.capped.list", "a,b,c,d,e");  // maxSize=3

// after
props.put("my.capped.list", "a,b,c");

// Before ConfigDef.parse / validating a list-typed config:
int MAX = 100; // match the ListSize.atMostOfSize(maxSize) bound
Object value = configs.get(name);
if (value instanceof List) {
    List<?> list = (List<?>) value;
    if (list.size() > MAX) {
        throw new IllegalArgumentException(
            name + " list size " + list.size() + " exceeds max " + MAX);
    }
}

// Narrow to a size-bounded List before handing to ConfigDef
static boolean isListWithinSize(Object v, int max) {
    return v instanceof List && ((List<?>) v).size() <= max;
}

try {
    configDef.parse(configs);
} catch (ConfigException e) {
    if (e.getMessage().contains("exceeds maximum list size")) {
        // trim the list to maxSize or reject the config outright
    } else { throw e; }
}

When it happens

Trigger: A config key validated with .validator(ListSize.atMostOfSize(N)) receives a List<String> longer than N elements. Triggered during KafkaConsumer/KafkaProducer/AdminClient construction or broker startup when ConfigDef.parse() / ensureValid() runs. Also reproducible by calling ConfigDef.validate() directly with an oversized list.

Common situations: Setting a capped list config like a custom validator-backed list (e.g. consumer group filters, broker listeners, plugin lists) with too many comma-separated entries. Misreading the documented cap and supplying extra items. Copying a large list from another environment without trimming to the limit.

Related errors

• Configuration 'name' values must not be null.
• Configuration 'name' must not be empty. Valid values include
• Configuration 'name' values must not be duplicated.
• Configuration 'name' values must not be empty.
• String must be one of: String.join(", ", validStrings)

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