apache/pulsar · error · IllegalArgumentException

jitterPercent must be in [0, 100]

Error message

jitterPercent must be in [0, 100]

What it means

Thrown by Backoff.Builder.jitterPercent when the supplied jitter percentage is outside the allowed [0, 100] range. Jitter is applied as a percentage of the computed backoff delay, so negative or >100 values are invalid and rejected eagerly at build time to fail fast rather than produce nonsensical retry delays.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/util/Backoff.java:228

         */
        public Builder mandatoryStop(Duration mandatoryStop) {
            this.mandatoryStop = mandatoryStop;
            return this;
        }

        /**
         * Sets the jitter percentage applied to each returned delay. The actual jitter is symmetric:
         * the returned value is multiplied by a uniform random factor in
         * {@code [1 - jitterPercent/200, 1 + jitterPercent/200)}. Defaults to 10. Set to 0 to disable
         * jitter.
         *
         * @param jitterPercent the jitter percentage, must be in {@code [0, 100]}
         * @return this builder
         * @throws IllegalArgumentException if {@code jitterPercent} is outside {@code [0, 100]}
         */
        public Builder jitterPercent(double jitterPercent) {
            if (jitterPercent < 0 || jitterPercent > 100) {
                throw new IllegalArgumentException("jitterPercent must be in [0, 100]");
            }
            this.jitterPercent = jitterPercent;
            return this;
        }

        Builder clock(Clock clock) {
            this.clock = clock;
            return this;
        }

        /**
         * Builds a new {@link Backoff} instance with the configured parameters.
         *
         * @return a new Backoff
         */
        public Backoff build() {
            return new Backoff(initialDelay, maxBackoff, mandatoryStop, jitterPercent, clock);
        }

View on GitHub (pinned to 820761864e)

Solutions

1. Clamp or validate the configured value to [0, 100] before passing it to jitterPercent
2. Convert fractions to percent (multiply by 100) if your config stores ratios
3. Fix the configuration source providing the jitter value
4. Choose a sensible default (e.g. 20) when the input is missing or malformed

Example fix

// before
new Backoff.Builder().jitterPercent(cfg.getJitter()) // cfg.getJitter() = 0.2 (fraction)
// after
new Backoff.Builder().jitterPercent(Math.min(100, Math.max(0, cfg.getJitter() * 100)))

double jp = cfg.getJitterPercent();
if (jp < 0 || jp > 100 || !Double.isFinite(jp)) throw new IllegalArgumentException("jitterPercent out of [0,100]: " + jp);

static boolean isValidJitterPercent(double v) {
    return Double.isFinite(v) && v >= 0 && v <= 100;
}

try {
    builder.jitterPercent(jp);
} catch (IllegalArgumentException e) {
    builder.jitterPercent(20); // sane default
}

When it happens

Trigger: Calling Backoff.Builder().jitterPercent(x) with x < 0 or x > 100 — e.g. passing a ratio like 1.5 meaning 150% or intending a fraction (0.5) but exceeding 1.0 semantics differently.

Common situations: Confusing fraction (0.2 = 20%) with percent (20); reading jitter from config files with mis-scaled values; arithmetic producing NaN-adjacent or negative values from earlier computations; copy-pasting jitter settings between libraries with different units (ms vs %).

Related errors

• multiplier must be >= 1.0
• Timeout during delete operation
• Timeout during close operation
• Timeout during open-cursor operation
• Timeout during delete-cursors operation

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