MyCATApache/Mycat-Server · error · IllegalArgumentException

Buckets cannot be less than 0

Error message

Buckets cannot be less than 0

What it means

PartitionByJumpConsistentHash's checkBuckets() validates the bucket count before running the jump consistent hash. A negative bucket count is invalid because the algorithm requires a non-negative number of target buckets, so it throws this IllegalArgumentException. It is invoked from jumpConsistentHash() on every hash calculation.

Solutions

1. Set the buckets/partitionCount property to a positive integer equal to the number of dataNodes.
2. Validate the parsed config value before init (assert >= 0).
3. Fix any generator/script that emits negative counts into rule.xml.

Example fix

// before
<property name="partitionCount">-1</property>
// after
<property name="partitionCount">8</property>

if (buckets < 0) throw new IllegalArgumentException("buckets must be >= 0, got " + buckets);

try {
    int node = partitionByJumpConsistentHash.calculate(columnValue);
} catch (IllegalArgumentException e) {
    // configuration bug: fix partitionCount before retrying
}

When it happens

Trigger: Configuring a negative partitionCount/buckets value for the jump consistent hash rule; a property parsed to a negative int in rule.xml; passing buckets < 0 to jumpConsistentHash directly in tests or code.

Common situations: Typo like count=-1 or an arithmetic expression yielding a negative count; automated config generation producing negative values; confusing partitionCount with a delta value.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• can't find function of name
• Can't find valid data node(s) for some of specified node…
• nameSuffix , require name parameter cannot multiple breaks!
• new & old table config is not equal!
• only one rule can defined

AI-assisted analysis of MyCATApache/Mycat-Server@65f8d8beb7 (2026-09-11). Data as JSON: /api/errors/cda6a901f2ffe7f8. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/io/mycat/route/function/PartitionByJumpConsistentHash.java:49

	public static int jumpConsistentHash(final long key, final int buckets) {
        checkBuckets(buckets);
        long k = key;
        long b = -1;
        long j = 0;

        while (j < buckets) {
            b = j;
            k = k * CONSTANT + 1L;

            j = (long) ((b + 1L) * (JUMP / toDouble((k >>> 33) + 1L)));
        }
        return (int) b;
    }

    private static void checkBuckets(final int buckets) {
        if (buckets < 0) {
            throw new IllegalArgumentException("Buckets cannot be less than 0");
        }
    }

    private static double toDouble(final long n) {
        double d = n & UNSIGNED_MASK;
        if (n < 0) {
            d += 0x1.0p63;
        }
        return d;
    }

    public void setTotalBuckets(int totalBuckets) {
        this.totalBuckets = totalBuckets;
    }

    public int getTotalBuckets() {
        return totalBuckets;
    }

View on GitHub (pinned to 65f8d8beb7)