apache/pulsar · error · IllegalArgumentException

failoverThreshold must be larger than 0

Error message

failoverThreshold must be larger than 0

What it means

The Builder.failoverThreshold(int) setter validates that the failover threshold (the number of consecutive failed probes before switching to the backup cluster) is at least 1. Values below 1 make the failover logic meaningless, so an IllegalArgumentException is thrown.

Source

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

    public enum PulsarServiceState {
        Healthy,
        PreFail,
        Failed,
        PreRecover;
    }

    public static Builder builder() {
        return new Builder();
    }

    public static class Builder {

        private SameAuthParamsLookupAutoClusterFailover
                sameAuthParamsLookupAutoClusterFailover = new SameAuthParamsLookupAutoClusterFailover();

        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;

View on GitHub (pinned to 820761864e)

Solutions

1. Pass a positive integer (>= 1) to failoverThreshold.
2. In your config loading code, default unset values to a sane positive number (e.g. the documented default) before calling the builder.
3. Clamp or reject invalid values at your own configuration-validation layer with a clear message.

Example fix

// before
builder.failoverThreshold(config.getFailoverThreshold()); // 0 when unset

// after
int t = config.getFailoverThreshold() > 0 ? config.getFailoverThreshold() : 3;
builder.failoverThreshold(t);

int failoverThreshold = cfg.getFailoverThreshold();
if (failoverThreshold < 1) {
    failoverThreshold = 3;
}

try {
    builder.failoverThreshold(t);
} catch (IllegalArgumentException e) {
    log.warn("Invalid failoverThreshold, using default 3", e);
    builder.failoverThreshold(3);
}

When it happens

Trigger: Calling failoverThreshold(0) or failoverThreshold(negative) while configuring SameAuthParamsLookupAutoClusterFailover via its Builder, typically from a parsed config value that defaulted to 0.

Common situations: Config file/CLI flag left unset so an int field deserializes to 0 and is passed straight through; off-by-one edits trying to 'disable' failover by setting the threshold to 0.

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

• recoverThreshold must be larger than 0
• checkHealthyIntervalMs 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/e65377d6f93e2a3d. Report an issue: GitHub.