apache/pulsar · error · IllegalArgumentException

Invalid pulsar service : ${serviceName}

Error message

Invalid pulsar service : ${serviceName}

What it means

ServiceURI recognizes service names: binary ('pulsar'), 'http', and 'https' (plus broker/http/https variants per getServicePort's switch). If the scheme's service name is none of these, getServicePort's default branch throws 'Invalid pulsar service : <serviceName>'. This is a scheme typo or an unsupported scheme string.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/net/ServiceURI.java:236

        switch (serviceName.toLowerCase()) {
            case BINARY_SERVICE:
                if (serviceInfos.length == 0) {
                    port = BINARY_PORT;
                } else if (serviceInfos.length == 1 && serviceInfos[0].equalsIgnoreCase(SSL_SERVICE)) {
                    port = BINARY_TLS_PORT;
                } else {
                    throw new IllegalArgumentException("Invalid pulsar service : " + serviceName + "+"
                        + Arrays.toString(serviceInfos));
                }
                break;
            case HTTP_SERVICE:
                port = HTTP_PORT;
                break;
            case HTTPS_SERVICE:
                port = HTTPS_PORT;
                break;
            default:
                throw new IllegalArgumentException("Invalid pulsar service : " + serviceName);
        }
        return port;
    }

    /**
     * Create a new URI from the service URI which only specifies one of the hosts.
     * @return a pulsar service URI with a single host specified
     */
    public String selectOne() {
        StringBuilder sb = new StringBuilder();
        if (serviceName != null) {
            sb.append(serviceName);

            for (int i = 0; i < serviceInfos.length; i++) {
                sb.append('+').append(serviceInfos[i]);
            }
            sb.append("://");
        }

View on GitHub (pinned to 820761864e)

Solutions

1. Correct the scheme to one of: pulsar, pulsar+ssl, http, https, broker, broker+ssl (match the exact supported set).
2. If you intended TLS binary service use 'pulsar+ssl', not 'pulsar-ssl' or 'pulsars'.
3. Check the serviceUrl against the broker's advertised serviceUrl/advertisedListeners configuration.

Example fix

// before
ServiceURI u = ServiceURI.create("pulsars://broker:6651");
// after
ServiceURI u = ServiceURI.create("pulsar+ssl://broker:6651");

static final Set<String> VALID_SERVICES = Set.of("pulsar","broker","http","https");
static void assertKnownService(String serviceUrl) {
    String scheme = serviceUrl.substring(0, serviceUrl.indexOf(":"));
    String service = scheme.split("\\+")[0];
    if (!VALID_SERVICES.contains(service.toLowerCase())) {
        throw new IllegalArgumentException("Invalid pulsar service : " + service);
    }
}

static boolean isKnownServiceName(String service) {
    return Set.of("pulsar","broker","http","https").contains(service.toLowerCase());
}

try {
    ServiceURI uri = ServiceURI.create(serviceUrl);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Invalid pulsar service")) {
        // unknown scheme name: fix typo to pulsar/pulsar+ssl/http/https
    }
    throw e;
}

When it happens

Trigger: ServiceURI.create('pulsarx://host:6650'), 'PULSAR2://...', or a custom scheme that ServiceURI does not map to a known service; the service name is derived from the text before '+' in the URI scheme.

Common situations: Typo'd schemes ('pulsers://', 'pulsar-ssl://'); using 'grpc://' or another scheme unsupported by this parser; casing handled via equalsIgnoreCase so case is not the issue.

Related errors

• Invalid pulsar service : ${serviceName}+${serviceInfos}
• Invalid hostname : ${hostname}
• host must not be null
• the value ${strUri} in the `advertisedListeners` configure i
• Invalid key format

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