{"id":"e1cb34ef490365f0","repo":"apache/kafka","slug":"configuration-name-values-must-not-be-null","errorCode":null,"errorMessage":"Configuration 'name' values must not be null.","messagePattern":"Configuration 'name' values must not be null\\.","errorType":"validation","errorClass":"ConfigException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java","lineNumber":1063,"sourceCode":"\n        public static ValidList in(String... validStrings) {\n            return new ValidList(List.of(validStrings), true, false);\n        }\n\n        public static ValidList in(boolean isEmptyAllowed, String... validStrings) {\n            if (!isEmptyAllowed && validStrings.length == 0) {\n                throw new IllegalArgumentException(\"At least one valid string must be provided when empty values are not allowed\");\n            }\n            return new ValidList(List.of(validStrings), isEmptyAllowed, false);\n        }\n\n        @Override\n        public void ensureValid(final String name, final Object value) {\n            if (value == null) {\n                if (isNullAllowed)\n                    return;\n                else\n                    throw new ConfigException(\"Configuration '\" + name + \"' values must not be null.\");\n            }\n\n            @SuppressWarnings(\"unchecked\")\n            List<Object> values = (List<Object>) value;\n            if (!isEmptyAllowed && values.isEmpty()) {\n                String validString = this.validString.validStrings.isEmpty() ? \"any non-empty value\" : this.validString.toString();\n                throw new ConfigException(\"Configuration '\" + name + \"' must not be empty. Valid values include: \" + validString);\n            }\n\n            if (Set.copyOf(values).size() != values.size()) {\n                throw new ConfigException(\"Configuration '\" + name + \"' values must not be duplicated.\");\n            }\n\n            validateIndividualValues(name, values);\n        }\n\n        private void validateIndividualValues(String name, List<Object> values) {\n            boolean hasValidStrings = !validString.validStrings.isEmpty();","sourceCodeStart":1045,"sourceCodeEnd":1081,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java#L1045-L1081","documentation":"Thrown by ValidList.ensureValid (an inner Validator of ConfigDef) when a list-typed configuration receives a null value but the validator was constructed with isNullAllowed=false (the default for ValidList.in(...)). Kafka config validators run during ConfigDef.parse()/validate() to enforce the contract declared by the module defining the config. The message reports the offending config key in place of 'name'.","triggerScenarios":"A ConfigDef.ConfigKey using ValidList.in(...) or ValidList.anyNonDuplicateValues(false, false) is parsed, and the supplied properties Map has no entry for that key (and no default was defined), or explicitly maps the key to null. Also fires when code calls configDef.parse(map) with a Properties object where the key was put as null.","commonSituations":"Producer/consumer/admin/admin client configs that accept lists (e.g. bootstrap.servers supplied as a list validator, or plugin-specific list configs) when the property is omitted from a properties file or set to an empty placeholder. Happens often when migrating from a config that previously had a default to one that is now mandatory, or when env-var substitution leaves the value unset.","solutions":["Provide a non-null value for the named configuration key in your Properties/Map before constructing the Kafka client.","If the key is optional by design, ensure the ConfigDef registers it with a default value or use ValidList.anyNonDuplicateValues(isEmptyAllowed, true) so null is permitted.","Check that env-var/placeholder substitution (e.g. ${VAR}) actually resolved; an unresolved placeholder can surface as null."],"exampleFix":"// before\nprops.put(\"my.list.config\", null);\nnew KafkaProducer<>(props);\n\n// after\nprops.put(\"my.list.config\", \"a,b,c\");\nnew KafkaProducer<>(props);","handlingStrategy":"validation","validationCode":"// Before building the Kafka client, screen every List-typed config value:\nString key = \"my.list.config\";\nObject raw = configs.get(key);\nif (raw == null) {\n    throw new IllegalArgumentException(\"Config '\" + key + \"' is required (null not allowed).\");\n}\nif (!(raw instanceof List<?>)) {\n    throw new IllegalArgumentException(\"Config '\" + key + \"' must be a List, got \" + raw.getClass());\n}","typeGuard":"// Java has no runtime type guard; narrow explicitly before handing the map to Kafka:\nstatic List<?> requireList(Map<String, ?> configs, String key) {\n    Object v = configs.get(key);\n    if (!(v instanceof List<?>)) throw new IllegalArgumentException(key + \" must be a non-null List\");\n    return (List<?>) v;\n}","tryCatchPattern":"// Construction of KafkaProducer/KafkaConsumer parses configs and can throw:\ntry {\n    new KafkaProducer<>(props);\n} catch (ConfigException ce) {\n    // ce.getMessage() contains \"values must not be null\"\n    log.error(\"Invalid kafka config '{}': {}\", ce.getName(), ce.getMessage());\n    failFastOrUseDefaults(ce);\n}","preventionTips":["Never put null as a value in the Properties/Map passed to KafkaProducer, KafkaConsumer, or AdminClient — omit the key instead.","Run props through ConfigDef.parse(props) (or ConfigDef.validate(props)) in a bootstrap layer before client construction so the failure surfaces in your code, not inside Kafka.","Unit-test config assembly with the real ConfigDef so a null slips are caught at build time."],"tags":["config","kafka-client","validation","validator"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}