{"id":"c4d376add203b215","repo":"apache/kafka","slug":"the-provided-listener-name-is-null-or-empty-string","errorCode":null,"errorMessage":"The provided listener name is null or empty string","messagePattern":"The provided listener name is null or empty string","errorType":"validation","errorClass":"ConfigException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/network/ListenerName.java","lineNumber":42,"sourceCode":"import java.util.Objects;\n\npublic final class ListenerName {\n\n    private static final String CONFIG_STATIC_PREFIX = \"listener.name\";\n\n    /**\n     * Create an instance with the security protocol name as the value.\n     */\n    public static ListenerName forSecurityProtocol(SecurityProtocol securityProtocol) {\n        return new ListenerName(securityProtocol.name);\n    }\n\n    /**\n     * Create an instance with the provided value converted to uppercase.\n     */\n    public static ListenerName normalised(String value) {\n        if (Utils.isBlank(value)) {\n            throw new ConfigException(\"The provided listener name is null or empty string\");\n        }\n        return new ListenerName(value.toUpperCase(Locale.ROOT));\n    }\n\n    private final String value;\n\n    public ListenerName(String value) {\n        Objects.requireNonNull(value, \"value should not be null\");\n        this.value = value;\n    }\n\n    public String value() {\n        return value;\n    }\n\n    @Override\n    public boolean equals(Object o) {\n        if (!(o instanceof ListenerName))","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/network/ListenerName.java#L24-L60","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\nlisteners=PLAINTEXT://:9092,\n\n// after\nlisteners=PLAINTEXT://:9092","handlingStrategy":"validation","validationCode":"// Validate before calling ListenerName.normalised(value)\nString value = /* from config/user */;\nif (value == null || value.trim().isEmpty()) {\n    throw new IllegalArgumentException(\"listener name must be non-blank\");\n}\nListenerName listener = ListenerName.normalised(value);","typeGuard":"// Java has no primitive type guard for String content; use a static guard.\nstatic Optional<ListenerName> safeNormalised(String value) {\n    if (value == null || value.trim().isEmpty()) return Optional.empty();\n    return Optional.of(ListenerName.normalised(value));\n}","tryCatchPattern":"try {\n    ListenerName listener = ListenerName.normalised(value);\n} catch (ConfigException e) {\n    log.error(\"Invalid listener name '{}'\", value, e);\n    failStartup(e);\n}","preventionTips":["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."],"tags":["config","listener","broker-startup","kafka-config"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}