What causes "Configuration key.name is defined twice." in apache/kafka?

Inspect the stack trace to find the second define(...) call for the named key and remove it or guard it with a configKeys.containsKey(name) check.

apache/kafka · error · ConfigException

Configuration key.name is defined twice.

Error message

Configuration key.name is defined twice.

What it means

Thrown by ConfigDef.define(ConfigKey) when a ConfigKey with the same name has already been registered in this ConfigDef instance (configKeys.containsKey(key.name)). ConfigDef is a builder of known configuration keys; a duplicate define() call is a programming error in the code that constructs the schema, not a runtime/user config issue. The exception fires at definition time, before any properties are parsed.

Source

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

     *
     * @return new unmodifiable {@link Set} instance containing the keys
     */
    public Set<String> names() {
        return Collections.unmodifiableSet(configKeys.keySet());
    }

    public Map<String, Object> defaultValues() {
        Map<String, Object> defaultValues = new HashMap<>();
        for (ConfigKey key : configKeys.values()) {
            if (key.defaultValue != NO_DEFAULT_VALUE)
                defaultValues.put(key.name, key.defaultValue);
        }
        return defaultValues;
    }

    public ConfigDef define(ConfigKey key) {
        if (configKeys.containsKey(key.name)) {
            throw new ConfigException("Configuration " + key.name + " is defined twice.");
        }
        if (key.group != null && !groups.contains(key.group)) {
            groups.add(key.group);
        }
        configKeys.put(key.name, key);
        return this;
    }

    /**
     * Define a new configuration
     * @param name          the name of the config parameter
     * @param type          the type of the config
     * @param defaultValue  the default value to use if this config isn't present
     * @param validator     the validator to use in checking the correctness of the config
     * @param importance    the importance of this config
     * @param documentation the documentation string for the config
     * @param group         the group this config belongs to
     * @param orderInGroup  the order of this config in the group

View on GitHub (pinned to c31c9215e1)

Solutions

Inspect the stack trace to find the second define(...) call for the named key and remove it or guard it with a configKeys.containsKey(name) check.
When subclassing or composing ConfigDefs, call super definitions only once and avoid re-defining keys already provided by parent classes (AbstractConfig, ConnectorConfig, etc.).
If merging ConfigDefs programmatically, iterate new keys and skip any whose name already exists in the target configKeys map.
After a Kafka version upgrade, diff the keys your code defines against the keys now provided by the upstream base class to find collisions.

Example fix

// before
ConfigDef def = new ConfigDef()
    .define("my.key", Type.STRING, "x", Importance.HIGH, "doc")
    .define("my.key", Type.INT, 1, Importance.HIGH, "doc"); // duplicate name

// after
ConfigDef def = new ConfigDef()
    .define("my.key", Type.STRING, "x", Importance.HIGH, "doc")
    .define("my.other.key", Type.INT, 1, Importance.HIGH, "doc");

Defensive patterns

Strategy: validation

Validate before calling

// For Kafka Connect connector authors building a custom ConfigDef.
Set<String> defined = new HashSet<>();

public ConfigDef defineOnce(ConfigKey key) {
    if (!defined.add(key.name)) {
        throw new IllegalStateException(
            "Configuration '" + key.name + "' is already defined; remove the duplicate define() call.");
    }
    return configDef.define(key);
}
// Then route every define(...) through defineOnce(...) instead of calling configDef.define() directly.

Prevention

Maintain a single source of truth for config key names (constants / enum), never string-literal them in two places.
Wrap every ConfigDef.define(...) in a guard that tracks already-defined names.
Run a unit test that constructs the ConfigDef once and asserts no exception, catching duplicates at build time.
Avoid copy-pasting define() blocks when reusing configs across connectors; share a common ConfigDef base.

When it happens

Trigger: Calling configDef.define(...) twice with the same name; chaining helper methods like define(...).define(...) or .withClientSaslSupport().withClientSaslSupport(); a base ConfigDef subclass that re-defines a key its parent already defined; merging two ConfigDef objects whose key sets overlap without deduplication.

Common situations: Custom Kafka client library that extends an existing config definition list and accidentally re-adds a key already supplied by a parent (e.g. re-defining bootstrap.servers or acks); Connect connector developer copying boilerplate that includes a key already added by AbstractConfig or ConnectorConfig; test helper that builds a ConfigDef then calls a populate() method twice; version upgrade where a key previously added only in your subclass is now also added upstream so both register it.

Related errors

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