Netflix/Hystrix · error · IllegalArgumentException

The timeInMilliseconds must divide equally into numberOfBuck

Error message

The timeInMilliseconds must divide equally into numberOfBuckets. For example 1000/10 is ok, 1000/11 is not.

What it means

HystrixRollingNumber splits a rolling window of timeInMilliseconds into numberOfBuckets, computing bucketSizeInMilliseconds = timeInMilliseconds / numberOfBuckets. The constructor validates that the division is exact; a non-zero remainder means the window and buckets cannot represent consistent time slices, so an IllegalArgumentException is thrown at construction.

Source

Thrown at hystrix-core/src/main/java/com/netflix/hystrix/util/HystrixRollingNumber.java:83

     * @deprecated Please use {@link HystrixRollingNumber(int, int) instead}.  These values are no longer allowed to
     * be updated at runtime.
     */
    @Deprecated
    public HystrixRollingNumber(HystrixProperty<Integer> timeInMilliseconds, HystrixProperty<Integer> numberOfBuckets) {
        this(timeInMilliseconds.get(), numberOfBuckets.get());
    }

    public HystrixRollingNumber(int timeInMilliseconds, int numberOfBuckets) {
        this(ACTUAL_TIME, timeInMilliseconds, numberOfBuckets);
    }

    /* package for testing */ HystrixRollingNumber(Time time, int timeInMilliseconds, int numberOfBuckets) {
        this.time = time;
        this.timeInMilliseconds = timeInMilliseconds;
        this.numberOfBuckets = numberOfBuckets;

        if (timeInMilliseconds % numberOfBuckets != 0) {
            throw new IllegalArgumentException("The timeInMilliseconds must divide equally into numberOfBuckets. For example 1000/10 is ok, 1000/11 is not.");
        }
        this.bucketSizeInMillseconds = timeInMilliseconds / numberOfBuckets;

        buckets = new BucketCircularArray(numberOfBuckets);
    }

    /**
     * Increment the counter in the current bucket by one for the given {@link HystrixRollingNumberEvent} type.
     * <p>
     * The {@link HystrixRollingNumberEvent} must be a "counter" type <code>HystrixRollingNumberEvent.isCounter() == true</code>.
     * 
     * @param type
     *            HystrixRollingNumberEvent defining which counter to increment
     */
    public void increment(HystrixRollingNumberEvent type) {
        getCurrentBucket().getAdder(type).increment();
    }

View on GitHub (pinned to 5ce3bc58c3)

Solutions

1. Pick numBuckets that divides timeInMilliseconds evenly (e.g. 10000ms/10 buckets, 5000ms/10 buckets).
2. If the values come from config, validate the pair at startup: assert window % buckets == 0 and fail fast with a clear config error.
3. Keep the documented constraint that bucket duration (window/buckets) should be >= 100ms for meaningful metrics.

Example fix

# before
hystrix.command.orders.metrics.rollingStats.timeInMilliseconds=5000
hystrix.command.orders.metrics.rollingStats.numBuckets=12   # 5000 % 12 != 0

# after
hystrix.command.orders.metrics.rollingStats.timeInMilliseconds=6000
hystrix.command.orders.metrics.rollingStats.numBuckets=12   # 500ms buckets

static void checkRollingWindow(int timeMs, int numBuckets) {
    if (timeMs % numBuckets != 0) {
        throw new IllegalArgumentException("timeInMilliseconds (" + timeMs + ") must be divisible by numberOfBuckets (" + numBuckets + ")");
    }
}
// run against config values before building commands/thread pools

When it happens

Trigger: Constructing HystrixRollingNumber(timeInMilliseconds, numberOfBuckets) where timeInMilliseconds % numberOfBuckets != 0, e.g. new HystrixRollingNumber(1000, 11) or misconfigured metrics window properties (metrics.rollingStats.timeInMilliseconds not divisible by metrics.rollingStats.numBuckets) on commands or thread pools.

Common situations: Setting hystrix.command.<key>.metrics.rollingStats.timeInMilliseconds=5000 with numBuckets=12; copying example configs with incompatible pairs; unit tests instantiating HystrixRollingNumber directly with odd numbers.

Related errors

• unknown {} property: {}
• bad property value. property name '{}'. Expected int value,
• bad property value. property name '{}'. Expected correct enu
• You have set the bucket size to 0ms. Please set a positive
• The timeInMilliseconds must divide equally into numberOfBuck

AI-assisted analysis of Netflix/Hystrix@5ce3bc58c3 (2026-08-14). Data as JSON: /api/errors/301e514483bb8e5e. Report an issue: GitHub.