apache/kafka · error · ConfigException

Some configurations in are referred in the dependents, but n

Error message

Some configurations in are referred in the dependents, but not defined: joined

What it means

Thrown by ConfigDef.parse(Map) when undefinedDependentConfigs() returns a non-empty list: some ConfigKey was registered in the dependents list of another key but was never itself defined in this ConfigDef via define(...). Dependents express that one config should be set when another is set (used by recommenders and tooling); a dangling reference indicates a schema wiring bug. The offending names are joined with commas in the message.

Source

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

        return this;
    }

    /**
     * Parse and validate configs against this configuration definition. The input is a map of configs. It is expected
     * that the keys of the map are strings, but the values can either be strings or they may already be of the
     * appropriate type (int, string, etc). This will work equally well with either java.util.Properties instances or a
     * programmatically constructed map.
     *
     * @param props The configs to parse and validate.
     * @return Parsed and validated configs. The key will be the config name and the value will be the value parsed into
     * the appropriate type (int, string, etc).
     */
    public Map<String, Object> parse(Map<?, ?> props) {
        // Check all configurations are defined
        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;

View on GitHub (pinned to c31c9215e1)

Solutions

For every name listed in the exception message, add a corresponding define(...) call in the same ConfigDef, OR remove that name from every dependents list that references it.
Audit each ConfigKey.dependents list in your ConfigDef build code to ensure every referenced name is itself defined.
If you only need a subset of a parent ConfigDef, build the new ConfigDef by copying the specific ConfigKey objects (so dependents stay consistent) rather than re-typing them.
Run a unit test that calls configDef.parse(new HashMap<>()) during construction to surface dangling dependents early.

Example fix

// before
ConfigDef def = new ConfigDef()
    .define("ssl.keystore.password", Type.PASSWORD, null, Importance.HIGH, "doc",
           "Security", 1, Width.LONG, "Keystore password",
           java.util.Arrays.asList("ssl.keystore.location"), null); // location never defined

// after
ConfigDef def = new ConfigDef()
    .define("ssl.keystore.location", Type.STRING, null, Importance.HIGH, "doc")
    .define("ssl.keystore.password", Type.PASSWORD, null, Importance.HIGH, "doc",
           "Security", 1, Width.LONG, "Keystore password",
           java.util.Arrays.asList("ssl.keystore.location"), null);

Defensive patterns

Strategy: validation

Validate before calling

// Use validate() (non-throwing) instead of parse() to surface ALL dependent issues at once.
List<ConfigValue> results = configDef.validate(props);
List<ConfigValue> problems = results.stream()
    .filter(cv -> !cv.errorMessages().isEmpty())
    .collect(Collectors.toList());
if (!problems.isEmpty()) {
    String report = problems.stream()
        .map(cv -> cv.name() + ": " + String.join("; ", cv.errorMessages()))
        .collect(Collectors.joining("\n"));
    throw new IllegalStateException("Config definition is incomplete - undefined dependents:\n" + report);
}

Prevention

When a config declares dependents, ensure every dependent name is itself define()'d in the same ConfigDef.
Prefer configDef.validate(props) over configDef.parse(props) during development to collect all errors instead of failing on the first.
Unit-test the ConfigDef in isolation: construct it, call validate(emptyMap), and assert no 'referred in the dependents' messages.
Keep dependent name strings as constants shared with their define() call to prevent drift.

When it happens

Trigger: Building a ConfigDef where a key is listed in the dependents array (the 11-arg define(...) or ConfigKey constructor) but that dependent name is never itself defined; removing or renaming a ConfigKey definition while leaving stale references to it in other keys' dependents lists; copying a subset of a parent ConfigDef's keys but leaving dependents that point at omitted keys.

Common situations: Connect connector author copies keys from Kafka client config but omits ssl.keystore.location while still listing it as a dependent of ssl.keystore.password; refactor that renames a config key without updating the dependents references; partial port of a ConfigDef between modules.

Related errors

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