apache/pulsar · error · IllegalArgumentException

there are redundant configure for listener `${listenerName}`

Error message

there are redundant configure for listener `${listenerName}`

What it means

During broker startup, Pulsar parses the `advertisedListeners` configuration into named listeners. Each listener name may map to at most four URIs, one per supported scheme (pulsar, pulsar+ssl, http, https). If more than four comma-separated entries share the same listener name, the validator rejects the config with this IllegalArgumentException before the broker can start.

Source

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

            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 {
                    URI uri = URI.create(strUri);
                    if ("pulsar".equalsIgnoreCase(uri.getScheme())) {
                        if (pulsarAddress == null) {
                            pulsarAddress = uri;
                        } else {
                            throw new IllegalArgumentException("there are redundant configure for listener `"
                                    + entry.getKey() + "`");
                        }
                    } else if ("pulsar+ssl".equalsIgnoreCase(uri.getScheme())) {
                        if (pulsarSslAddress == null) {
                            pulsarSslAddress = uri;
                        } else {
                            throw new IllegalArgumentException("there are redundant configure for listener `"

View on GitHub (pinned to 820761864e)

Solutions

1. Edit broker.conf / advertisedListeners so each listener name has at most 4 URIs — one per scheme: pulsar://, pulsar+ssl://, http://, https://
2. Remove duplicate or obsolete URIs for the listener named in the message
3. Split genuinely different endpoints into separate listener names (e.g. `internal:...`, `external:...`) instead of piling URIs under one name
4. Restart the broker and confirm startup passes validation

Example fix

# before
advertisedListeners=external:pulsar://h1:6650,pulsar+ssl://h1:6651,http://h1:8080,https://h1:8443,pulsar://h2:6650
# after
advertisedListeners=external:pulsar://h1:6650,pulsar+ssl://h1:6651,http://h1:8080,https://h1:8443

Map<String,Integer> counts = new HashMap<>();
for (String entry : advertisedListeners.split(",")) {
    String name = entry.substring(0, entry.indexOf(':')).trim();
    counts.merge(name, 1, Integer::sum);
}
if (counts.values().stream().anyMatch(c -> c > 4))
    throw new IllegalArgumentException("a listener may have at most 4 URIs (one per scheme)");

try {
    startBroker(config);
} catch (IllegalArgumentException e) {
    log.error("Invalid advertisedListeners: {}", e.getMessage());
    throw new ConfigurationException(e.getMessage(), e);
}

When it happens

Trigger: Setting `advertisedListeners` in broker.conf / ServiceConfiguration with more than 4 `name:scheme://host:port` entries using the same listener name, e.g. five or more URIs separated by commas for one listener.

Common situations: Copy-paste accumulation of duplicated or obsolete listener URIs across config edits; generating the config from a script that appends an entry per protocol without de-duplicating; misunderstanding that a listener accepts at most one URI per scheme (max 4 total).

Related errors

• must not specify `${hostPort}` to different listener.
• the value ${strUri} in the `advertisedListeners` configure i
• Configuration field 'transactionPendingAckBatchedWriteMaxDel
• 'transactionLogBatchedWriteMaxRecords' value must be greater
• 'transactionLogBatchedWriteMaxSize' value must be greater th

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