apache/kafka · error · ConfigException

Configuration 'name' must not be empty. Valid values include

Error message

Configuration 'name' must not be empty. Valid values include: validString

What it means

Thrown by ValidList.ensureValid when the supplied list is empty and the validator was built with isEmptyAllowed=false (via ValidList.in(boolean, String...)). Kafka rejects empty lists here because the config requires at least one element; the message appends either the allowed value set or 'any non-empty value' when the validator constrains only count, not contents.

Source

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

                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();

            for (Object value : values) {
                if (value instanceof String) {
                    String string = (String) value;
                    if (string.isEmpty()) {
                        throw new ConfigException("Configuration '" + name + "' values must not be empty.");
                    }

View on GitHub (pinned to c31c9215e1)

Solutions

1. Supply at least one valid element for the named list config (e.g. change "my.list=" to "my.list=value1").
2. Confirm each element is one of the validStrings printed in the message when the validator enumerates allowed values.
3. If an empty list is genuinely acceptable, change the ConfigKey definition to ValidList.in(true, ...) or anyNonDuplicateValues(true, isNullAllowed).

Example fix

// before
props.put("my.list.config", "");

// after
props.put("my.list.config", "read,write");

// Ensure a non-empty list is supplied for every config defined with ValidList.in(false, ...):
for (String requiredListKey : List.of("bootstrap.servers", "sasl.kerberos.principal" /* etc. */)) {
    Object v = configs.get(requiredListKey);
    if (v instanceof List<?> && ((List<?>) v).isEmpty()) {
        throw new IllegalArgumentException("Config '" + requiredListKey + "' must not be empty.");
    }
}

null

try {
    ConfigDef def = ...; // the producer/consumer ConfigDef
    def.parse(props);
} catch (ConfigException ce) {
    if (ce.getMessage().contains("must not be empty")) {
        // surface to operator with the list of valid values printed in ce.getMessage()
        reportMissingRequired(ce);
    } else throw ce;
}

When it happens

Trigger: Calling ConfigDef.parse()/validate() on properties where the named list config resolves to an empty list (e.g. value "" split into [], or an explicit empty Collections.emptyList()) while the ConfigKey was defined with ValidList.in(false, ...) or ValidList.anyNonDuplicateValues(false, isNullAllowed).

Common situations: Comma-separated list configs (e.g. custom interceptor.classes, or broker/listener configs using list validators) configured with an empty string in server.properties or a properties file. Also seen when a templated deployment leaves a list placeholder blank.

Related errors

• Configuration 'name' values must not be duplicated.
• Configuration 'name' values must not be empty.
• Configuration 'name' values must not be null.
• 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/c98e310eef38a879.json. Report an issue: GitHub.