{"id":"5ceb72bccc6bc08a","repo":"apache/kafka","slug":"configuration-key-name-is-defined-twice","errorCode":null,"errorMessage":"Configuration key.name is defined twice.","messagePattern":"Configuration key\\.name is defined twice\\.","errorType":"validation","errorClass":"ConfigException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java","lineNumber":133,"sourceCode":"     *\n     * @return new unmodifiable {@link Set} instance containing the keys\n     */\n    public Set<String> names() {\n        return Collections.unmodifiableSet(configKeys.keySet());\n    }\n\n    public Map<String, Object> defaultValues() {\n        Map<String, Object> defaultValues = new HashMap<>();\n        for (ConfigKey key : configKeys.values()) {\n            if (key.defaultValue != NO_DEFAULT_VALUE)\n                defaultValues.put(key.name, key.defaultValue);\n        }\n        return defaultValues;\n    }\n\n    public ConfigDef define(ConfigKey key) {\n        if (configKeys.containsKey(key.name)) {\n            throw new ConfigException(\"Configuration \" + key.name + \" is defined twice.\");\n        }\n        if (key.group != null && !groups.contains(key.group)) {\n            groups.add(key.group);\n        }\n        configKeys.put(key.name, key);\n        return this;\n    }\n\n    /**\n     * Define a new configuration\n     * @param name          the name of the config parameter\n     * @param type          the type of the config\n     * @param defaultValue  the default value to use if this config isn't present\n     * @param validator     the validator to use in checking the correctness of the config\n     * @param importance    the importance of this config\n     * @param documentation the documentation string for the config\n     * @param group         the group this config belongs to\n     * @param orderInGroup  the order of this config in the group","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java#L115-L151","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nConfigDef def = new ConfigDef()\n    .define(\"my.key\", Type.STRING, \"x\", Importance.HIGH, \"doc\")\n    .define(\"my.key\", Type.INT, 1, Importance.HIGH, \"doc\"); // duplicate name\n\n// after\nConfigDef def = new ConfigDef()\n    .define(\"my.key\", Type.STRING, \"x\", Importance.HIGH, \"doc\")\n    .define(\"my.other.key\", Type.INT, 1, Importance.HIGH, \"doc\");","handlingStrategy":"validation","validationCode":"// For Kafka Connect connector authors building a custom ConfigDef.\nSet<String> defined = new HashSet<>();\n\npublic ConfigDef defineOnce(ConfigKey key) {\n    if (!defined.add(key.name)) {\n        throw new IllegalStateException(\n            \"Configuration '\" + key.name + \"' is already defined; remove the duplicate define() call.\");\n    }\n    return configDef.define(key);\n}\n// Then route every define(...) through defineOnce(...) instead of calling configDef.define() directly.","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["config","configdef","duplicate","programming-error"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}