{"id":"94d79f0542f6df54","repo":"apache/kafka","slug":"exceeds-maximum-list-size-of-maxsize","errorCode":null,"errorMessage":"exceeds maximum list size of [maxSize].","messagePattern":"exceeds maximum list size of \\[maxSize\\]\\.","errorType":"validation","errorClass":"ConfigException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java","lineNumber":1296,"sourceCode":"    }\n\n    public static class ListSize implements Validator {\n        final int maxSize;\n\n        private ListSize(final int maxSize) {\n            this.maxSize = maxSize;\n        }\n\n        public static ListSize atMostOfSize(final int maxSize) {\n            return new ListSize(maxSize);\n        }\n\n        @Override\n        public void ensureValid(final String name, final Object value) {\n            @SuppressWarnings(\"unchecked\")\n            List<String> values = (List<String>) value;\n            if (values.size() > maxSize) {\n                throw new ConfigException(name, value, \"exceeds maximum list size of [\" + maxSize + \"].\");\n            }\n        }\n\n        @Override\n        public String toString() {\n            return \"List containing maximum of \" + maxSize + \" elements\";\n        }\n    }\n\n    public static class ConfigKey {\n        public final String name;\n        public final Type type;\n        public final String documentation;\n        public final Object defaultValue;\n        public final Validator validator;\n        public final Importance importance;\n        public final String group;\n        public final int orderInGroup;","sourceCodeStart":1278,"sourceCodeEnd":1314,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java#L1278-L1314","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Count entries of the offending config value and trim the list to at most maxSize (the number shown in the message).","Find the config key in ConfigDef by searching for ListSize.atMostOfSize(...) usage and confirm the documented maximum for that property.","If the higher count is genuinely required, raise the cap in the ConfigDef definition (requires source change) or split workload across multiple config keys."],"exampleFix":"// before\nprops.put(\"my.capped.list\", \"a,b,c,d,e\");  // maxSize=3\n\n// after\nprops.put(\"my.capped.list\", \"a,b,c\");","handlingStrategy":"validation","validationCode":"// Before ConfigDef.parse / validating a list-typed config:\nint MAX = 100; // match the ListSize.atMostOfSize(maxSize) bound\nObject value = configs.get(name);\nif (value instanceof List) {\n    List<?> list = (List<?>) value;\n    if (list.size() > MAX) {\n        throw new IllegalArgumentException(\n            name + \" list size \" + list.size() + \" exceeds max \" + MAX);\n    }\n}","typeGuard":"// Narrow to a size-bounded List before handing to ConfigDef\nstatic boolean isListWithinSize(Object v, int max) {\n    return v instanceof List && ((List<?>) v).size() <= max;\n}","tryCatchPattern":"try {\n    configDef.parse(configs);\n} catch (ConfigException e) {\n    if (e.getMessage().contains(\"exceeds maximum list size\")) {\n        // trim the list to maxSize or reject the config outright\n    } else { throw e; }\n}","preventionTips":["Cap list size at the source (CLI parser, UI, env var) before it reaches Kafka config parsing.","Inspect ConfigDef.register(...) / validators to learn each key's ListSize.atMostOfSize bound and assert against it in tests.","Avoid unbounded user input flowing directly into list-valued configs; map/whitelist accepted entries first."],"tags":["config","validation","kafka-client","broker-startup"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}