apache/pulsar · error · IllegalArgumentException

the configure entry `advertisedListeners` is invalid. becaus

Error message

the configure entry `advertisedListeners` is invalid. because ${entry} do not contain listener name

What it means

IllegalArgumentException thrown by MultipleListenerValidator.parseAdvertisedListeners when an advertisedListeners entry has no listener-name prefix, i.e. no ':' before any name (index of ':' is <= 0). Each entry must be in the form <listenerName>:<scheme>://<host>:<port>; a bare URL like pulsar://host:6650 is rejected because the parser cannot determine which listener it belongs to.

Source

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

                        ? override.getBrokerHttpsUrl() : fallback.getBrokerHttpsUrl())
                .build();
    }

    private static Map<String, AdvertisedListener> parseAdvertisedListeners(ServiceConfiguration config) {
        if (StringUtils.isBlank(config.getAdvertisedListeners())) {
            return new LinkedHashMap<>();
        }
        Map<String, List<String>> listeners = new LinkedHashMap<>();
        // Trim whitespace around comma-separated entries so configurations split across multiple
        // lines or padded for readability are accepted, and skip empties.
        for (final String raw : StringUtils.split(config.getAdvertisedListeners(), ",")) {
            String str = StringUtils.trim(raw);
            if (StringUtils.isEmpty(str)) {
                continue;
            }
            int index = str.indexOf(":");
            if (index <= 0) {
                throw new IllegalArgumentException("the configure entry `advertisedListeners` is invalid. because "
                        + str + " do not contain listener name");
            }
            String listenerName = StringUtils.trim(str.substring(0, index));
            validateListenerName(listenerName);
            String value = StringUtils.trim(str.substring(index + 1));
            listeners.computeIfAbsent(listenerName, k -> new ArrayList<>(2));
            listeners.get(listenerName).add(value);
        }
        final Map<String, AdvertisedListener> result = new LinkedHashMap<>();
        final Map<String, Set<String>> reverseMappings = new LinkedHashMap<>();
        for (final Map.Entry<String, List<String>> entry : listeners.entrySet()) {
            if (entry.getValue().size() > 4) {
                throw new IllegalArgumentException("there are redundant configure for listener `" + entry.getKey()
                        + "`");
            }
            URI pulsarAddress = null, pulsarSslAddress = null, pulsarHttpAddress = null, pulsarHttpsAddress = null;
            for (final String strUri : entry.getValue()) {
                try {

View on GitHub (pinned to 820761864e)

Solutions

1. Prefix every entry with a listener name: internal:pulsar://host:6650
2. Ensure the name portion is non-empty and contains only ASCII letters, digits, underscore, hyphen
3. Validate the comma-separated list has one 'name:url' pair per entry

Example fix

// before
advertisedListeners=pulsar://broker.example.com:6650
// after
advertisedListeners=internal:pulsar://broker.example.com:6650

for (String entry : advertisedListeners.split(",")) {
    entry = entry.trim();
    int idx = entry.indexOf(':');
    if (idx <= 0 || !entry.substring(0, idx).matches("[A-Za-z0-9_-]+")) {
        throw new IllegalArgumentException("advertisedListeners entry '" + entry + "' must be <listenerName>:<url>");
    }
}

When it happens

Trigger: Configuring advertisedListeners=pulsar://host:6650 (missing 'name:' prefix); an entry starting with ':' (empty name yields index 0, also rejected); whitespace-only or malformed segments left after comma splitting.

Common situations: Copying legacy advertisedAddress-style values into the newer advertisedListeners property without adding the name prefix; migration from old configs on upgrade; string templating dropping the name portion.

Related errors

• listener name must not be blank
• listener name `${name}` must contain only ASCII letters, dig
• the `advertisedListeners` configuration does not contain an
• bindAddresses: malformed: ${address}
• bindAddresses: conflicting listener names for ${address}: `$

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