apache/pulsar · error · IllegalArgumentException

the value ${strUri} in the `advertisedListeners` configure i

Error message

the value ${strUri} in the `advertisedListeners` configure is invalid

What it means

Any failure while parsing a single URI inside `advertisedListeners` — including malformed URI syntax and the redundant/duplicate-listener IllegalArgumentExceptions thrown in the same try block — is caught and rethrown as this IllegalArgumentException wrapping the original value and cause. It indicates one specific comma-separated entry in the configuration is invalid.

Source

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

                        }
                    } else if ("https".equalsIgnoreCase(uri.getScheme())) {
                        if (pulsarHttpsAddress == null) {
                            pulsarHttpsAddress = uri;
                        } else {
                            throw new IllegalArgumentException("there are redundant configure for listener `"
                                    + entry.getKey() + "`");
                        }
                    }

                    String hostPort = formatHostPort(uri);
                    Set<String> sets = reverseMappings.computeIfAbsent(hostPort, k -> new TreeSet<>());
                    sets.add(entry.getKey());
                    if (sets.size() > 1) {
                        throw new IllegalArgumentException("must not specify `" + hostPort
                                + "` to different listener.");
                    }
                } catch (Throwable cause) {
                    throw new IllegalArgumentException("the value " + strUri + " in the `advertisedListeners` "
                            + "configure is invalid", cause);
                }
            }
            result.put(entry.getKey(), AdvertisedListener.builder()
                    .brokerServiceUrl(pulsarAddress)
                    .brokerServiceUrlTls(pulsarSslAddress)
                    .brokerHttpUrl(pulsarHttpAddress)
                    .brokerHttpsUrl(pulsarHttpsAddress)
                    .build());
        }
        return result;
    }

    /**
     * Synthesize an {@link AdvertisedListener} for the internal listener from the legacy port
     * configuration (`brokerServicePort`, `brokerServicePortTls`, `webServicePort`,
     * `webServicePortTls`). Returns {@code null} if no binary port and no web port is set; the caller
     * is then responsible for raising an error if the internal listener is still missing after

View on GitHub (pinned to 820761864e)

Solutions

Read the `cause` of the exception: it names the exact failing entry and the real reason (duplicate scheme, shared host:port, or URI syntax)
Validate the URI parses (URI.create) and has a supported scheme (pulsar, pulsar+ssl, http, https) before deploying the config
Remove or fix the offending entry in `advertisedListeners`

Example fix

// before
advertisedListeners=external:pulsar://h1:notaport
// after
advertisedListeners=external:pulsar://h1:6650

Defensive patterns

Strategy: try-catch

Validate before calling

for (String entry : advertisedListeners.split(",")) {
    String value = entry.substring(entry.indexOf(':') + 1).trim();
    URI uri = URI.create(value);
    String scheme = uri.getScheme();
    if (scheme == null || !Set.of("pulsar","pulsar+ssl","http","https").contains(scheme.toLowerCase()))
        throw new IllegalStateException("unsupported URI: " + value);
    if (uri.getHost() == null || uri.getPort() == -1)
        throw new IllegalStateException("URI missing host/port: " + value);
}

Try / catch

try {
    startBroker(config);
} catch (IllegalArgumentException e) {
    // message is "the value <strUri> in the `advertisedListeners` configure is invalid"
    log.error("Bad advertisedListeners entry: {} (cause: {})", e.getMessage(), e.getCause());
    throw e;
}

Prevention

Inspect e.getCause() to find the real failing entry and reason
Pre-validate each URI (scheme, host, port) before deployment
Quote values properly in YAML/properties to avoid mangling
Keep one change per config edit to isolate breakage

When it happens

Trigger: `advertisedListeners` contains a malformed URI (e.g. `pulsar://host:notaport`), a duplicate-scheme entry, or a host:port shared with another listener; any of these gets wrapped with the offending strUri in the message.

Common situations: Typos in scheme (e.g. `pulsar:/host:6650`), missing port, spaces or stray characters in the value, duplicate URIs from copy-paste, YAML/properties quoting issues mangling the value.

Related errors

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