apache/kafka · error · ConfigException

Missing required configuration "key.name" which has no defau

Error message

Missing required configuration "key.name" which has no default value.

What it means

Thrown by ConfigDef.parseValue when a ConfigKey has defaultValue == NO_DEFAULT_VALUE (the sentinel at ConfigDef.java:93) and the supplied properties map does not contain that key. Such keys are required: with no default and no user value there is nothing valid to assign, so parsing aborts with a ConfigException naming the missing key.

Source

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

        List<String> undefinedConfigKeys = undefinedDependentConfigs();
        if (!undefinedConfigKeys.isEmpty()) {
            String joined = undefinedConfigKeys.stream().map(String::toString).collect(Collectors.joining(","));
            throw new ConfigException("Some configurations in are referred in the dependents, but not defined: " + joined);
        }
        // parse all known keys
        Map<String, Object> values = new HashMap<>();
        for (ConfigKey key : configKeys.values())
            values.put(key.name, parseValue(key, props.get(key.name), props.containsKey(key.name)));
        return values;
    }

    Object parseValue(ConfigKey key, Object value, boolean isSet) {
        Object parsedValue;
        if (isSet) {
            parsedValue = parseType(key.name, value, key.type);
        // props map doesn't contain setting, the key is required because no default value specified - its an error
        } else if (NO_DEFAULT_VALUE.equals(key.defaultValue)) {
            throw new ConfigException("Missing required configuration \"" + key.name + "\" which has no default value.");
        } else {
            // otherwise assign setting its default value
            parsedValue = key.defaultValue;
        }
        if (key.validator instanceof ValidList && parsedValue instanceof List) {
            List<?> originalListValue = (List<?>) parsedValue;
            parsedValue = originalListValue.stream().distinct().collect(Collectors.toList());
            if (originalListValue.size() != ((List<?>) parsedValue).size()) {
                LOGGER.warn("Configuration key \"{}\" contains duplicate values. Duplicates will be removed. The original value " +
                        "is: {}, the updated value is: {}", key.name, originalListValue, parsedValue);
            }
        }
        if (key.validator != null) {
            key.validator.ensureValid(key.name, parsedValue);
        }
        return parsedValue;
    }

View on GitHub (pinned to c31c9215e1)

Solutions

1. Read the exception message for the exact key name, then add that key with a non-empty value to the Properties/Map passed to the client or connector constructor.
2. Double-check the spelling and case of the key against the official ConfigDef (e.g. bootstrap.servers, not bootstrap.server).
3. If constructing programmatically, ensure the value is actually inserted into the map (a null value still satisfies containsKey but may fail later validation; the key must be present).
4. If the property is supplied via env var / file / Vault, verify the substitution actually produced a value before constructing the client.
5. If the key is optional in your use case, give the ConfigDef entry a real default value instead of NO_DEFAULT_VALUE when you own the schema.

Example fix

// before
Properties props = new Properties();
props.put("client.id", "my-app");
new KafkaProducer<>(props); // throws: Missing required configuration "bootstrap.servers"

// after
Properties props = new Properties();
props.put("bootstrap.servers", "localhost:9092");
props.put("client.id", "my-app");
new KafkaProducer<>(props);

// Required Kafka client keys - check presence & non-empty BEFORE constructing the client.
String[] required = { "bootstrap.servers", "key.serializer", "value.serializer" }; // adjust per client
for (String k : required) {
    String v = props.getProperty(k);
    if (v == null || v.trim().isEmpty()) {
        throw new IllegalArgumentException("Missing required Kafka config '" + k + "'. Provide it in properties/env/file.");
    }
}
// For a custom ConfigDef, derive the list dynamically:
// configDef.configKeys().values().stream()
//     .filter(k -> k.defaultValue == ConfigDef.NO_DEFAULT_VALUE)
//     .map(k -> k.name).forEach(k -> assertSupplied(props, k));

try {
    return new KafkaProducer<>(props);
} catch (ConfigException e) {
    if (e.getMessage().startsWith("Missing required configuration")) {
        // Surface a clearer message and a stable exit code; do NOT silently default.
        throw new IllegalArgumentException("Startup blocked - " + e.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: Constructing a Kafka client (KafkaProducer, KafkaConsumer, KafkaAdminClient, Connect worker, KafkaStreams) without supplying a required option such as bootstrap.servers, schema.registry.url (in Confluent stack), group.id for a consumer using group-based assignors, or a connector-specific required property; passing a Properties/Map that omits a key whose ConfigDef entry used the NO_DEFAULT_VALUE default.

Common situations: New producer/consumer that forgot bootstrap.servers; consumer without group.id; Connect connector config missing connector-specific required fields (e.g. topics for a source connector); typo in the property name so the supplied value is ignored; environment variable expansion that produced an empty value and the empty key was not put in the map; cluster deployment where required secrets were not injected.

Related errors

• Telemetry is not enabled. Set config `${ConsumerConfig.ENABL
• You must provide a valid ${ConsumerConfig.GROUP_ID_CONFIG} i
• Could not load config provider class or one of its dependenc
• Configuration 'name' values must not be null.
• Configuration 'name' must not be empty. Valid values include

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