apache/pulsar · error · IllegalArgumentException

checkHealthyIntervalMs must be larger than 0

Error message

checkHealthyIntervalMs must be larger than 0

What it means

The Builder.checkHealthyIntervalMs(int) setter validates that the health-probe interval is at least 1 millisecond. A zero or negative interval would cause immediate/spammed or unschedulable probes, so IllegalArgumentException is thrown.

Source

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

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

        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;
        }

View on GitHub (pinned to 820761864e)

Solutions

1. Pass a positive millisecond value (>= 1), typically thousands of ms (e.g. 30000).
2. Default unset/zero config values to the documented interval before calling the builder.
3. Sanity-check that your time-unit conversion (seconds/hours -> ms) is correct.

Example fix

// before
builder.checkHealthyIntervalMs((int) TimeUnit.SECONDS.toMillis(cfg.getIntervalSec())); // intervalSec=0

// after
long ms = TimeUnit.SECONDS.toMillis(cfg.getIntervalSec() > 0 ? cfg.getIntervalSec() : 30);
builder.checkHealthyIntervalMs((int) Math.max(1, ms));

int intervalMs = cfg.getCheckHealthyIntervalMs();
if (intervalMs < 1) {
    intervalMs = 30_000;
}

try {
    builder.checkHealthyIntervalMs(ms);
} catch (IllegalArgumentException e) {
    log.warn("Invalid checkHealthyIntervalMs, using 30000ms", e);
    builder.checkHealthyIntervalMs(30_000);
}

When it happens

Trigger: Calling checkHealthyIntervalMs(0) or a negative value on the SameAuthParamsLookupAutoClusterFailover Builder, e.g. when a duration config property was left unset and parsed as 0.

Common situations: Duration values expressed in seconds converted incorrectly (e.g. 0 seconds for 'use default'); typo in the property key so the fallback 0 is used.

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
• testTopic can not be blank
• 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/42a53c80593de498. Report an issue: GitHub.