apache/kafka · error · ConfigException

Expected a comma separated list.

Error message

Expected a comma separated list.

What it means

Thrown by the Type.LIST branch of ConfigDef.parseType when the value is neither a java.util.List nor a String. LIST-typed configs (e.g. bootstrap.servers is LIST<STRING>, client.dns.lookup, config.providers, metric.reporters) are accepted either as a ready-made List or as a comma-separated String that gets split on comma-with-whitespace. Any other runtime type (Number, Boolean, Map, Object[]) is rejected.

Source

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

                    else
                        throw new ConfigException(name, value, "Expected value to be a 64-bit integer (long), but it was a " + value.getClass().getName());
                case DOUBLE:
                    if (value instanceof Number)
                        return ((Number) value).doubleValue();
                    else if (value instanceof String)
                        return Double.parseDouble(trimmed);
                    else
                        throw new ConfigException(name, value, "Expected value to be a double, but it was a " + value.getClass().getName());
                case LIST:
                    if (value instanceof List)
                        return value;
                    else if (value instanceof String)
                        if (trimmed.isEmpty())
                            return List.of();
                        else
                            return Arrays.asList(COMMA_WITH_WHITESPACE.split(trimmed, -1));
                    else
                        throw new ConfigException(name, value, "Expected a comma separated list.");
                case CLASS:
                    if (value instanceof Class)
                        return value;
                    else if (value instanceof String) {
                        return Utils.loadClass(trimmed, Object.class);
                    } else
                        throw new ConfigException(name, value, "Expected a Class instance or class name.");
                default:
                    throw new IllegalStateException("Unknown type.");
            }
        } catch (NumberFormatException e) {
            throw new ConfigException(name, value, "Not a number of type " + type);
        } catch (ClassNotFoundException e) {
            throw new ConfigException(name, value, "Class " + value + " could not be found.");
        }
    }

    /**

View on GitHub (pinned to c31c9215e1)

Solutions

1. Pass a comma-separated String (e.g. bootstrap.servers="k1:9092,k2:9092").
2. Or pass a java.util.List<String> built with List.of(...) or Arrays.asList(...).
3. If a config framework yields String[] or Set, convert with new ArrayList<>(Arrays.asList(arr)) or new ArrayList<>(set) before handing the value to Kafka.
4. For empty list, pass an empty String or List.of(); avoid null unless the key is documented as nullable.

Example fix

// before
props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG,
         new String[]{"k1:9092","k2:9092"}); // array -> ConfigException

// after
props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG,
         Arrays.asList("k1:9092","k2:9092"));
// or
props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "k1:9092,k2:9092");

Object v = rawValue;
if (!(v instanceof List) && !(v instanceof String)) {
    throw new IllegalArgumentException("config '" + key + "' must be a List or comma-separated string");
}

public static boolean isListValue(Object v) {
    return v instanceof List || v instanceof String;
}

try {
    configDef.parse(configs);
} catch (ConfigException e) {
    if (e.getMessage().contains("Expected a comma separated list")) {
        // wrap or coerce value to a String/List and retry
    } else throw e;
}

When it happens

Trigger: Calling ConfigDef.parse/validate (transitively, any Kafka client constructor) with a LIST-typed config set to a non-List, non-String object — e.g. a String[] array, a Set, a Map, or a single Number where a list was expected.

Common situations: Spring/Typesafe Config returning a String[] or ConfigObject instead of List<String>; passing a java.util.Set where List is expected; a property placeholder that resolved to null and was then substituted with a default of the wrong type; building bootstrap.servers from a single String in code that happens to be a non-String object after templating.

Related errors

• Invalid url in bootstrap.servers: {url}
• Expected value to be a 64-bit integer (long), but it was a v
• Expected value to be a double, but it was a value.getClass()
• Expected a Class instance or class name.
• Invalid url in bootstrap.servers: {url}

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