apache/pulsar · error · java.lang.IllegalArgumentException

${fieldName} must use the broker binary protocol (pulsar://

Error message

${fieldName} must use the broker binary protocol (pulsar:// or pulsar+ssl://); got '${url}'.

What it means

Thrown by validatePulsarServiceUrl in PulsarClientBuilderV5 when the service URL set on the client builder does not use the broker's binary protocol scheme (pulsar:// or pulsar+ssl://). The Pulsar client connects to brokers over a binary TCP protocol; HTTP(S) URLs belong to the admin/web service, so passing one means the client would have no way to speak to the broker. The library rejects it eagerly at builder configuration time rather than failing later with an opaque connection error.

Source

Thrown at pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/PulsarClientBuilderV5.java:596

     * mistake is passing the admin/web service URL ({@code http://...}) where a
     * broker URL is expected — call that out specifically. The v4 client used to
     * silently fail far downstream with cryptic connection errors; here we fail
     * fast at configure time with a message the user can act on.
     */
    private static void validatePulsarServiceUrl(String url, String fieldName) {
        if (url == null || url.isBlank()) {
            throw new IllegalArgumentException(fieldName + " must not be null or blank");
        }
        if (url.startsWith("pulsar://") || url.startsWith("pulsar+ssl://")) {
            return;
        }
        if (url.startsWith("http://") || url.startsWith("https://")) {
            throw new IllegalArgumentException(fieldName + " must use the broker binary protocol "
                    + "(pulsar:// or pulsar+ssl://); got '" + url + "'. This looks like the admin/web "
                    + "service URL — pass the broker service URL instead (typically port 6650, or "
                    + "6651 for TLS).");
        }
        throw new IllegalArgumentException(fieldName + " must use the broker binary protocol "
                + "(pulsar:// or pulsar+ssl://); got '" + url + "'.");
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Replace the URL with the broker binary service URL, typically pulsar://<host>:6650 or pulsar+ssl://<host>:6651
2. If you only have the admin URL, derive the broker URL: same host, scheme pulsar:// (or pulsar+ssl:// for TLS), port 6650 (or 6651 for TLS)
3. Check your environment/config variables for the right value — many deployments expose both PULSAR_WEB_SERVICE_URL (http) and PULSAR_BROKER_SERVICE_URL (pulsar)

Example fix

// before
PulsarClient.builder().serviceUrl("http://localhost:8080");
// after
PulsarClient.builder().serviceUrl("pulsar://localhost:6650");

boolean isValidBrokerUrl(String url) {
    return url != null && (url.startsWith("pulsar://") || url.startsWith("pulsar+ssl://"));
}
if (!isValidBrokerUrl(cfg.brokerUrl)) throw new IllegalArgumentException("Use pulsar://host:6650 or pulsar+ssl://host:6651, not an http(s) admin URL");

boolean isBrokerServiceUrl(String url) {
    return url != null && url.startsWith("pulsar://") || (url != null && url.startsWith("pulsar+ssl://"));
}

try {
    builder.serviceUrl(url);
} catch (IllegalArgumentException e) {
    log.error("Bad service URL: {}", e.getMessage());
}

When it happens

Trigger: Calling serviceUrl(...) (or a connectionPolicy that derives the URL) on PulsarClientBuilderV5 with a URL whose scheme is not pulsar:// or pulsar+ssl:// — e.g. http:// or https://, an empty scheme, or a typo like pulsar//. When an http(s) URL is passed, the message additionally hints it looks like the admin/web service URL.

Common situations: Copy-pasting the admin URL (http://broker:8080, typically from a Kubernetes service or the standalone broker's webServicePort) instead of the broker service URL; confusing port 8080 (HTTP admin) with port 6650 (binary broker) or 6651 (TLS broker); building the URL from environment variables that only carry the HTTP endpoint.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• Timeout during delete operation
• Timeout during close operation
• Timeout during open-cursor operation
• Timeout during delete-cursors operation
• Timeout during managed ledger terminate

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