apache/kafka · error · ConfigException

The provided listener name is null or empty string

Error message

The provided listener name is null or empty string

What it means

Thrown by ListenerName.normalised(String) (a ConfigException) when Utils.isBlank(value) is true, i.e. the supplied listener name is null, empty, or only whitespace. Kafka listener names identify a listener advertised in the 'listeners' config and must be non-blank because they become the prefix key (listener.name.<name>) for per-listener settings. A blank name would produce ambiguous/unresolvable config keys, so the library rejects it during configuration parsing.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/network/ListenerName.java:42

import java.util.Objects;

public final class ListenerName {

    private static final String CONFIG_STATIC_PREFIX = "listener.name";

    /**
     * Create an instance with the security protocol name as the value.
     */
    public static ListenerName forSecurityProtocol(SecurityProtocol securityProtocol) {
        return new ListenerName(securityProtocol.name);
    }

    /**
     * Create an instance with the provided value converted to uppercase.
     */
    public static ListenerName normalised(String value) {
        if (Utils.isBlank(value)) {
            throw new ConfigException("The provided listener name is null or empty string");
        }
        return new ListenerName(value.toUpperCase(Locale.ROOT));
    }

    private final String value;

    public ListenerName(String value) {
        Objects.requireNonNull(value, "value should not be null");
        this.value = value;
    }

    public String value() {
        return value;
    }

    @Override
    public boolean equals(Object o) {
        if (!(o instanceof ListenerName))

View on GitHub (pinned to c31c9215e1)

Solutions

Inspect the 'listeners' (and 'advertised.listeners') lines in server.properties for empty tokens, trailing commas, or a missing protocol-name segment; every entry must be <NAME>://<host>:<port>.
If constructing a ListenerName in code, validate it is non-blank before calling normalised(), or use the ListenerName(String) constructor directly only when you can guarantee non-null.
Check any templating/ENV substitution (e.g. ${LISTENER_NAME}) actually resolves to a non-empty value at startup.

Example fix

// before
listeners=PLAINTEXT://:9092,

// after
listeners=PLAINTEXT://:9092

Defensive patterns

Strategy: validation

Validate before calling

// Validate before calling ListenerName.normalised(value)
String value = /* from config/user */;
if (value == null || value.trim().isEmpty()) {
    throw new IllegalArgumentException("listener name must be non-blank");
}
ListenerName listener = ListenerName.normalised(value);

Type guard

// Java has no primitive type guard for String content; use a static guard.
static Optional<ListenerName> safeNormalised(String value) {
    if (value == null || value.trim().isEmpty()) return Optional.empty();
    return Optional.of(ListenerName.normalised(value));
}

Try / catch

try {
    ListenerName listener = ListenerName.normalised(value);
} catch (ConfigException e) {
    log.error("Invalid listener name '{}'", value, e);
    failStartup(e);
}

Prevention

Source listener names from constants/enums wherever possible, not free-form user input.
Validate all broker config values (listeners, advertised.listeners) at startup before constructing ListenerName.
Trim and check whitespace-only strings explicitly; Utils.isBlank catches null, empty, and whitespace.

When it happens

Trigger: Calling ListenerName.normalised(value) with a null, empty, or whitespace-only string; also reached indirectly when the broker/client parses the 'listeners' or 'advertised.listeners' config and encounters an entry whose name token is blank (e.g. '://host:9092' or a trailing comma).

Common situations: Malformed 'listeners' property such as 'listeners=SASL_SSL://host:9092,' (trailing comma yields an empty token), a missing/typo'd listener name, or programmatic admin/producer construction that passes an empty listener identifier. Most common after editing server.properties by hand or templating config that interpolates an unset variable.

Related errors

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