apache/pulsar · error · IllegalArgumentException

pulsarServiceUrlArray contains a blank value at index

Error message

pulsarServiceUrlArray contains a blank value at index 

What it means

Builder.pulsarServiceUrlArray iterates the given URLs and rejects any entry that is null/blank, reporting the offending index. Each cluster entry must be a real service URL for the probe to connect to.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/SameAuthParamsLookupAutoClusterFailover.java:364

            return this;
        }

        public Builder markTopicNotFoundAsAvailable(boolean markTopicNotFoundAsAvailable) {
            sameAuthParamsLookupAutoClusterFailover.markTopicNotFoundAsAvailable = markTopicNotFoundAsAvailable;
            return this;
        }

        public Builder pulsarServiceUrlArray(String[] pulsarServiceUrlArray) {
            if (pulsarServiceUrlArray == null || pulsarServiceUrlArray.length == 0) {
                throw new IllegalArgumentException("pulsarServiceUrlArray can not be empty");
            }
            sameAuthParamsLookupAutoClusterFailover.pulsarServiceUrlArray = pulsarServiceUrlArray;
            int pulsarServiceLen = pulsarServiceUrlArray.length;
            HashSet<String> uniqueChecker = new HashSet<>();
            for (int i = 0; i < pulsarServiceLen; i++) {
                String pulsarService = pulsarServiceUrlArray[i];
                if (StringUtils.isBlank(pulsarService)) {
                    throw new IllegalArgumentException("pulsarServiceUrlArray contains a blank value at index " + i);
                }
                if (pulsarService.startsWith("http") || pulsarService.startsWith("HTTP")) {
                    throw new IllegalArgumentException("SameAuthParamsLookupAutoClusterFailover does not support HTTP"
                            + " protocol pulsar service url so far.");
                }
                if (!uniqueChecker.add(pulsarService)) {
                    throw new IllegalArgumentException("pulsarServiceUrlArray contains duplicated value "
                            + pulsarServiceUrlArray[i]);
                }
            }
            return this;
        }

        public SameAuthParamsLookupAutoClusterFailover build() {
            String[] pulsarServiceUrlArray = sameAuthParamsLookupAutoClusterFailover.pulsarServiceUrlArray;
            if (pulsarServiceUrlArray == null) {
                throw new IllegalArgumentException("pulsarServiceUrlArray can not be empty");
            }

View on GitHub (pinned to 820761864e)

Solutions

1. Trim and filter out empty/null entries from the array before passing it to the builder.
2. Fix the source config so every listed cluster has a URL (remove stray commas/blank lines).
3. Validate the array yourself before calling the builder to get a clearer error message.

Example fix

// before
builder.pulsarServiceUrlArray("pulsar://a:6650,,pulsar://b:6650".split(","));

// after
String[] urls = Arrays.stream("pulsar://a:6650,,pulsar://b:6650".split(","))
    .map(String::trim).filter(s -> !s.isEmpty()).toArray(String[]::new);
builder.pulsarServiceUrlArray(urls);

String[] urls = Arrays.stream(raw.split(","))
    .map(String::trim).filter(s -> !s.isEmpty()).toArray(String[]::new);
for (int i = 0; i < urls.length; i++) {
    if (urls[i] == null || urls[i].isBlank()) {
        throw new IllegalArgumentException("Blank cluster URL at index " + i);
    }
}

try {
    builder.pulsarServiceUrlArray(urls);
} catch (IllegalArgumentException e) {
    log.error("Cluster URL list contains a blank entry: {}", e.getMessage());
    throw new ConfigurationException(e.getMessage(), e);
}

When it happens

Trigger: Passing an array containing null, "", or whitespace-only entries to pulsarServiceUrlArray, typically from an improperly parsed comma-separated list that yields empty strings (e.g. "pulsar://a:6650,,pulsar://b:6650").

Common situations: Trailing commas in a config list; YAML list items left empty; entries with only spaces after trimming failures; null entries from a partially initialized collection.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• failoverThreshold must be larger than 0
• recoverThreshold must be larger than 0
• checkHealthyIntervalMs must be larger than 0
• testTopic can not be blank
• pulsarServiceUrlArray can not be empty

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