apache/pulsar · error · IllegalArgumentException

listener name must not be blank

Error message

listener name must not be blank

What it means

IllegalArgumentException thrown by MultipleListenerValidator.validateListenerName when the listener name is null or blank. Listener names are used as map keys in advertisedListeners and embedded in URLs, so an empty name is meaningless and rejected before the character-set check.

Source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/broker/validator/MultipleListenerValidator.java:70

            throw new IllegalArgumentException("host must not be null");
        }
        String unbracketed = host.startsWith("[") && host.endsWith("]")
                ? host.substring(1, host.length() - 1) : host;
        if (NetUtil.isValidIpV6Address(unbracketed)) {
            return "[" + unbracketed + "]:" + uri.getPort();
        }
        return host + ":" + uri.getPort();
    }

    /**
     * Validate a listener name. Listener names must be non-blank and contain only ASCII letters,
     * digits, underscore, and hyphen so they are safe to embed in URLs without encoding.
     *
     * @throws IllegalArgumentException if the name is null, blank, or contains disallowed characters.
     */
    public static void validateListenerName(String name) {
        if (StringUtils.isBlank(name)) {
            throw new IllegalArgumentException("listener name must not be blank");
        }
        if (!LISTENER_NAME_PATTERN.matcher(name).matches()) {
            throw new IllegalArgumentException("listener name `" + name + "` must contain only ASCII"
                    + " letters, digits, underscore, or hyphen");
        }
    }

    /**
     * Validate `advertisedListeners` and `internalListenerName`, returning the parsed listener map.
     * <p>
     * This method mutates the supplied {@link ServiceConfiguration}: when {@code internalListenerName}
     * is blank, it is written back with the resolved fallback value (the first parsed listener if any,
     * otherwise {@value ServiceConfiguration#DEFAULT_INTERNAL_LISTENER_NAME}) so that subsequent reads
     * from the config see the effective value.
     * <ol>
     * <li>`advertisedListeners` is a comma-separated list of endpoints in the form
     *     `listener:scheme://host:port`. Supported schemes are `pulsar`, `pulsar+ssl`, `http`, and `https`.
     * <li>A listener name may be repeated to define multiple endpoints (e.g. binary and HTTPS) for the

View on GitHub (pinned to 820761864e)

Solutions

1. Set a non-empty listener name (ASCII letters, digits, underscore, hyphen)
2. Check the rendered config (broker.conf or Helm values) for empty name variables
3. Trim whitespace around the name in generated configs

Example fix

// before
String name = env.get("LISTENER_NAME"); // empty
validator.validateListenerName(name);
// after
String name = Objects.requireNonNullElse(env.get("LISTENER_NAME"), "default");
validator.validateListenerName(name);

if (name == null || name.isBlank()) {
    throw new IllegalArgumentException("listener name must not be blank");
}

static boolean isValidListenerName(String name) {
    return name != null && name.matches("[A-Za-z0-9_-]+");
}

When it happens

Trigger: Calling validateListenerName(null) or with an all-whitespace string; parseAdvertisedListeners hits it when an advertisedListeners entry has an empty name portion (e.g. ":pulsar://host:6650" or a leading comma producing an empty segment after trim) — though those are mostly filtered, a blank name can still slip through from programmatic callers.

Common situations: Templated configs where a variable holding the listener name was empty; k8s/Helm values leaving a listenerName unset; string concatenation producing a dangling colon prefix.

Related errors

• listener name `${name}` must contain only ASCII letters, dig
• the configure entry `advertisedListeners` is invalid. becaus
• Timeout during delete operation
• Timeout during close operation
• Timeout during open-cursor operation

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/0e187a21ddce2417. Report an issue: GitHub.