apache/pulsar · error · IllegalArgumentException

jitterPercent must be in [0, 100]

Error message

jitterPercent must be in [0, 100]

What it means

The BackoffPolicy constructor validates that jitterPercent lies within the inclusive range 0-100. Jitter is expressed as a percentage of the computed backoff delay used to randomize retries and avoid thundering herds; a value outside [0,100] is meaningless (negative jitter or >100% would exceed the base delay). The library throws IllegalArgumentException immediately at construction so misconfiguration fails fast.

Source

Thrown at pulsar-client-api-v5/src/main/java/org/apache/pulsar/client/api/v5/config/BackoffPolicy.java:55

@ToString
public final class BackoffPolicy {

    /** Default jitter percentage applied when not explicitly specified. */
    public static final double DEFAULT_JITTER_PERCENT = 10.0;

    private final Duration initialInterval;
    private final Duration maxInterval;
    private final double multiplier;
    private final double jitterPercent;

    private BackoffPolicy(Duration initialInterval, Duration maxInterval, double multiplier, double jitterPercent) {
        Objects.requireNonNull(initialInterval, "initialInterval must not be null");
        Objects.requireNonNull(maxInterval, "maxInterval must not be null");
        if (multiplier < 1.0) {
            throw new IllegalArgumentException("multiplier must be >= 1.0");
        }
        if (jitterPercent < 0 || jitterPercent > 100) {
            throw new IllegalArgumentException("jitterPercent must be in [0, 100]");
        }
        this.initialInterval = initialInterval;
        this.maxInterval = maxInterval;
        this.multiplier = multiplier;
        this.jitterPercent = jitterPercent;
    }

    /**
     * @return the base delay before the first reconnection attempt
     */
    public Duration initialInterval() {
        return initialInterval;
    }

    /**
     * @return the maximum delay between reconnection attempts
     */
    public Duration maxInterval() {

View on GitHub (pinned to 820761864e)

Solutions

1. Set jitterPercent to an integer in [0, 100] (e.g. 20 for 20% jitter).
2. If your source value is a fraction, convert it: jitterPercent = (int)(fraction * 100).
3. Clamp or reject the value in your config loading layer before constructing BackoffPolicy.

Example fix

// before
BackoffPolicy p = BackoffPolicy.builder()
    .initialInterval(Duration.ofMillis(100))
    .maxInterval(Duration.ofSeconds(30))
    .multiplier(2.0)
    .jitterPercent(150) // IllegalArgumentException
    .build();

// after
BackoffPolicy p = BackoffPolicy.builder()
    .initialInterval(Duration.ofMillis(100))
    .maxInterval(Duration.ofSeconds(30))
    .multiplier(2.0)
    .jitterPercent(50) // valid: 50% jitter
    .build();

int jp = config.jitterPercent();
if (jp < 0 || jp > 100) {
    throw new IllegalArgumentException("jitterPercent must be in [0, 100], got: " + jp);
}
BackoffPolicy p = BackoffPolicy.builder().jitterPercent(jp).build();

static boolean isValidJitterPercent(int v) { return v >= 0 && v <= 100; }

try {
    policy = BackoffPolicy.builder().jitterPercent(cfg).build();
} catch (IllegalArgumentException e) {
    log.warn("Bad jitterPercent, falling back to default", e);
    policy = BackoffPolicy.builder().build();
}

When it happens

Trigger: Calling new BackoffPolicy(initialInterval, maxInterval, multiplier, jitterPercent) or a builder method like jitterPercent(int) with a value < 0 or > 100, e.g. BackoffPolicy.builder().jitterPercent(150) or .jitterPercent(-10).

Common situations: Confusing jitterPercent (0-100) with a fraction (0-1) and passing 0.5 then multiplying by 100 twice; reading a value from external config where units are misdocumented; copying a multiplier-style config where 1.5 meant '50% jitter' but was entered as 150.

Understand the failure class

Background: "Invalid configuration value" and "Unsupported/Unknown setting value" errors: why libraries reject your config strings, numbers, and types — this error's family across 30 libraries.

Related errors

• connectionsPerBroker must be >= 1
• configuredService should not be an instance of SystemTopicBa
• The shared resource doesn't support thread pool configurati
• No resources have been configured while using shareConfigure
• multiplier must be >= 1.0

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