apache/pulsar · error · IllegalArgumentException

testTopic can not be blank

Error message

testTopic can not be blank

What it means

The Builder.testTopic(String) setter rejects a blank test topic. The probe uses this topic to check cluster health; a blank topic cannot be resolved. (Note the guard also calls TopicName.get(testTopic), which itself throws on a malformed topic string, so invalid topic formats surface here too.)

Source

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

        public Builder recoverThreshold(int recoverThreshold) {
            if (recoverThreshold < 1) {
                throw new IllegalArgumentException("recoverThreshold must be larger than 0");
            }
            sameAuthParamsLookupAutoClusterFailover.recoverThreshold = recoverThreshold;
            return this;
        }

        public Builder checkHealthyIntervalMs(int checkHealthyIntervalMs) {
            if (checkHealthyIntervalMs < 1) {
                throw new IllegalArgumentException("checkHealthyIntervalMs must be larger than 0");
            }
            sameAuthParamsLookupAutoClusterFailover.checkHealthyIntervalMs = checkHealthyIntervalMs;
            return this;
        }

        public Builder testTopic(String testTopic) {
            if (StringUtils.isBlank(testTopic) && TopicName.get(testTopic) != null) {
                throw new IllegalArgumentException("testTopic can not be blank");
            }
            sameAuthParamsLookupAutoClusterFailover.testTopic = testTopic;
            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++) {

View on GitHub (pinned to 820761864e)

Solutions

1. Provide a fully qualified topic name such as persistent://public/default/__cluster_health_check.
2. In config loading, fail fast (with your own message) if the test-topic property is null/blank instead of passing it through.
3. Verify the topic string matches Pulsar's topic-name format (domain://tenant/namespace/topic).

Example fix

// before
builder.testTopic(System.getenv("HEALTH_TOPIC")); // null when unset

// after
String topic = System.getenv("HEALTH_TOPIC");
if (topic == null || topic.isBlank()) {
    topic = "persistent://public/default/__cluster_health_check";
}
builder.testTopic(topic);

if (testTopic == null || testTopic.isBlank()) {
    throw new IllegalArgumentException("testTopic must be set to a fully qualified topic name");
}

try {
    builder.testTopic(topic);
} catch (IllegalArgumentException e) {
    log.warn("Invalid testTopic '{}', using default", topic, e);
    builder.testTopic("persistent://public/default/__cluster_health_check");
}

When it happens

Trigger: Calling testTopic(null), testTopic(""), or testTopic(" ") on the SameAuthParamsLookupAutoClusterFailover Builder, or passing a string that TopicName.get cannot parse.

Common situations: YAML/properties config where the test topic key is present but empty; environment variable not set and substituted as empty string; typo in the topic name format (missing persistent:// or namespace).

Related errors

• failoverThreshold must be larger than 0
• recoverThreshold must be larger than 0
• checkHealthyIntervalMs must be larger than 0
• pulsarServiceUrlArray can not be empty
• pulsarServiceUrlArray contains a blank value at index

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