apache/kafka · error · ConfigException

String must be one of (case insensitive): String.join(", ",

Error message

String must be one of (case insensitive): String.join(", ", validStrings)

What it means

Thrown by CaseInsensitiveValidString.ensureValid when the supplied value is null OR its uppercase form is not in the validator's pre-uppercased validStrings set. Unlike ValidString this validator normalizes case via toUpperCase(Locale.ROOT) on both sides, so 'ssl', 'Ssl', 'SSL' are equivalent; the message still lists the (uppercased) permitted values for clarity.

Source

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

    public static class CaseInsensitiveValidString implements Validator {

        final Set<String> validStrings;

        private CaseInsensitiveValidString(List<String> validStrings) {
            this.validStrings = validStrings.stream()
                .map(s -> s.toUpperCase(Locale.ROOT))
                .collect(Collectors.toSet());
        }

        public static CaseInsensitiveValidString in(String... validStrings) {
            return new CaseInsensitiveValidString(Arrays.asList(validStrings));
        }

        @Override
        public void ensureValid(String name, Object o) {
            String s = (String) o;
            if (s == null || !validStrings.contains(s.toUpperCase(Locale.ROOT))) {
                throw new ConfigException(name, o, "String must be one of (case insensitive): " + String.join(", ", validStrings));
            }
        }

        public String toString() {
            return "(case insensitive) [" + String.join(", ", validStrings) + "]";
        }
    }

    public static class NonNullValidator implements Validator {
        @Override
        public void ensureValid(String name, Object value) {
            if (value == null) {
                // Pass in the string null to avoid the spotbugs warning
                throw new ConfigException(name, "null", "entry must be non null");
            }
        }

        public String toString() {

View on GitHub (pinned to c31c9215e1)

Solutions

Use one of the values listed in the message (case does not matter, but spelling and punctuation must match: underscores, digits).
If the value comes from an env var or file, trim it and confirm there are no trailing whitespace or hidden characters.
If you hit the null branch, provide an explicit default for the ConfigKey or always set the property.

Example fix

// before
props.put("security.protocol", "sssl");  // typo

// after
props.put("security.protocol", "ssl");

Defensive patterns

Strategy: validation

Validate before calling

// Case-insensitive membership check mirroring CaseInsensitiveValidString:
Set<String> allowedUpper = allowed.stream().map(s -> s.toUpperCase(Locale.ROOT)).collect(Collectors.toSet());
String val = (String) configs.get(key);
if (val == null || !allowedUpper.contains(val.toUpperCase(Locale.ROOT))) {
    throw new IllegalArgumentException(key + " must be one of (case insensitive) " + allowed);
}

Type guard

null

Try / catch

try {
    def.parse(props);
} catch (ConfigException ce) {
    if (ce.getMessage().contains("case insensitive)")) {
        // Normalize and retry with the canonical-cased value
        String canonical = findCanonical(ce.value().toString().toUpperCase(Locale.ROOT));
        props.put(ce.getName(), canonical);
    } else throw ce;
}

Prevention

Always store config strings in the canonical case shown in Kafka docs to avoid mismatches.
When accepting user input, uppercase before comparing against the allow-list.
Document the case-insensitive contract to operators so they don't try to 'fix' a working value by changing case.

When it happens

Trigger: A ConfigKey validated with CaseInsensitiveValidString.in("SSL","PLAINTEXT","SASL_PLAINTEXT","SASL_SSL") receives a value whose uppercase form is none of these, or receives null. Triggered during ConfigDef.parse() when ensureValid is invoked.

Common situations: Subtle typos that case normalization cannot fix ("SSl" still matches "SSL", but "SSSL" does not), whitespace or hidden characters in the value, or genuinely unsupported protocol names. The null branch fires when a no-default optional config is omitted in certain code paths.

Related errors

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