apache/kafka · error · ConfigException

String may not be empty

Error message

String may not be empty

What it means

Thrown by NonEmptyStringWithoutControlChars.ensureValid when the value is non-null and isEmpty(). Unlike NonEmptyString, this validator also scans for ISO control characters; the empty-string branch is checked first and emits this specific message. The validator deliberately tolerates null (returns early) because a missing value for the config is caught separately when checking mandatory parameters, so null is treated as 'not yet supplied'.

Source

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

    }

    public static class NonEmptyStringWithoutControlChars implements Validator {

        public static NonEmptyStringWithoutControlChars nonEmptyStringWithoutControlChars() {
            return new NonEmptyStringWithoutControlChars();
        }

        @Override
        public void ensureValid(String name, Object value) {
            String s = (String) value;

            if (s == null) {
                // This can happen during creation of the config object due to no default value being defined for the
                // name configuration - a missing name parameter is caught when checking for mandatory parameters,
                // thus we can ok a null value here
                return;
            } else if (s.isEmpty()) {
                throw new ConfigException(name, value, "String may not be empty");
            }

            // Check name string for illegal characters
            ArrayList<Integer> foundIllegalCharacters = new ArrayList<>();

            for (int i = 0; i < s.length(); i++) {
                if (Character.isISOControl(s.codePointAt(i))) {
                    foundIllegalCharacters.add(s.codePointAt(i));
                }
            }

            if (!foundIllegalCharacters.isEmpty()) {
                throw new ConfigException(name, value, "String may not contain control sequences but had the following ASCII chars: " +
                        foundIllegalCharacters.stream().map(Object::toString).collect(Collectors.joining(", ")));
            }
        }

        public String toString() {

View on GitHub (pinned to c31c9215e1)

Solutions

1. Provide a non-empty, control-character-free value for the named config.
2. If the field is optional in your workflow, omit the key rather than assigning an empty string (null is accepted).
3. Audit property files and env-var substitutions for empty assignments to the offending key.

Example fix

// before
props.put("listener.name.internal.sasl.enabled.mechanisms", "");

// after
props.put("listener.name.internal.sasl.enabled.mechanisms", "PLAIN");

// NonEmptyStringWithoutControlChars rejects empty (but tolerates null).
// Common on 'group.id', 'client.id' style identifiers — pre-check:
String[] nonEmptyKeys = {"group.id", "client.id", "transactional.id"};
for (String k : nonEmptyKeys) {
    Object v = props.get(k);
    if (v instanceof String && ((String) v).isEmpty()) {
        throw new IllegalArgumentException(k + " may not be empty");
    }
}

// Wrap in a value type that cannot be constructed empty:
static final class NonEmptyStr {
    final String value;
    NonEmptyStr(String v) {
        if (v == null || v.isEmpty()) throw new IllegalArgumentException("empty");
        this.value = v;
    }
}

try {
    new KafkaConsumer<>(props);
} catch (ConfigException ce) {
    if (ce.getMessage().equals("String may not be empty")) {
        log.error("Kafka config '{}' is empty; supply a value", ce.getName());
        failStartup();
    } else throw ce;
}

When it happens

Trigger: A ConfigKey validated with NonEmptyStringWithoutControlChars.nonEmptyStringWithoutControlChars() is supplied an empty string. Most prominently used for the broker/controller 'name' (listeners/advertised.listeners naming) and similar identifier configs. Triggered during ConfigDef.parse().

Common situations: Identifier or name fields (listener names, topic names where this validator is reused, plugin config keys) set to an empty string via a properties file (`name=`) or programmatic empty assignment. Common in templated deployments where a placeholder was not filled.

Related errors

• Configuration 'name' values must not be empty.
• String must be non-empty
• Configuration 'name' values must not be null.
• Configuration 'name' must not be empty. Valid values include
• Configuration 'name' values must not be duplicated.

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