apache/kafka · error · ConfigException

Configuration 'name' values must not be null.

Error message

Configuration 'name' values must not be null.

What it means

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'.

Source

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

        public static ValidList in(String... validStrings) {
            return new ValidList(List.of(validStrings), true, false);
        }

        public static ValidList in(boolean isEmptyAllowed, String... validStrings) {
            if (!isEmptyAllowed && validStrings.length == 0) {
                throw new IllegalArgumentException("At least one valid string must be provided when empty values are not allowed");
            }
            return new ValidList(List.of(validStrings), isEmptyAllowed, false);
        }

        @Override
        public void ensureValid(final String name, final Object value) {
            if (value == null) {
                if (isNullAllowed)
                    return;
                else
                    throw new ConfigException("Configuration '" + name + "' values must not be null.");
            }

            @SuppressWarnings("unchecked")
            List<Object> values = (List<Object>) value;
            if (!isEmptyAllowed && values.isEmpty()) {
                String validString = this.validString.validStrings.isEmpty() ? "any non-empty value" : this.validString.toString();
                throw new ConfigException("Configuration '" + name + "' must not be empty. Valid values include: " + validString);
            }

            if (Set.copyOf(values).size() != values.size()) {
                throw new ConfigException("Configuration '" + name + "' values must not be duplicated.");
            }

            validateIndividualValues(name, values);
        }

        private void validateIndividualValues(String name, List<Object> values) {
            boolean hasValidStrings = !validString.validStrings.isEmpty();

View on GitHub (pinned to c31c9215e1)

Solutions

1. Provide a non-null value for the named configuration key in your Properties/Map before constructing the Kafka client.
2. 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.
3. Check that env-var/placeholder substitution (e.g. ${VAR}) actually resolved; an unresolved placeholder can surface as null.

Example fix

// before
props.put("my.list.config", null);
new KafkaProducer<>(props);

// after
props.put("my.list.config", "a,b,c");
new KafkaProducer<>(props);

// Before building the Kafka client, screen every List-typed config value:
String key = "my.list.config";
Object raw = configs.get(key);
if (raw == null) {
    throw new IllegalArgumentException("Config '" + key + "' is required (null not allowed).");
}
if (!(raw instanceof List<?>)) {
    throw new IllegalArgumentException("Config '" + key + "' must be a List, got " + raw.getClass());
}

// Java has no runtime type guard; narrow explicitly before handing the map to Kafka:
static List<?> requireList(Map<String, ?> configs, String key) {
    Object v = configs.get(key);
    if (!(v instanceof List<?>)) throw new IllegalArgumentException(key + " must be a non-null List");
    return (List<?>) v;
}

// Construction of KafkaProducer/KafkaConsumer parses configs and can throw:
try {
    new KafkaProducer<>(props);
} catch (ConfigException ce) {
    // ce.getMessage() contains "values must not be null"
    log.error("Invalid kafka config '{}': {}", ce.getName(), ce.getMessage());
    failFastOrUseDefaults(ce);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• 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)
• String must be one of (case insensitive): String.join(", ",

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