{"record":{"id":"cda6a901f2ffe7f8","repo":"MyCATApache/Mycat-Server","slug":"buckets-cannot-be-less-than-0","errorCode":null,"errorMessage":"Buckets cannot be less than 0","messagePattern":"Buckets cannot be less than 0","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/main/java/io/mycat/route/function/PartitionByJumpConsistentHash.java","lineNumber":49,"sourceCode":"\n\tpublic static int jumpConsistentHash(final long key, final int buckets) {\n        checkBuckets(buckets);\n        long k = key;\n        long b = -1;\n        long j = 0;\n\n        while (j < buckets) {\n            b = j;\n            k = k * CONSTANT + 1L;\n\n            j = (long) ((b + 1L) * (JUMP / toDouble((k >>> 33) + 1L)));\n        }\n        return (int) b;\n    }\n\n    private static void checkBuckets(final int buckets) {\n        if (buckets < 0) {\n            throw new IllegalArgumentException(\"Buckets cannot be less than 0\");\n        }\n    }\n\n    private static double toDouble(final long n) {\n        double d = n & UNSIGNED_MASK;\n        if (n < 0) {\n            d += 0x1.0p63;\n        }\n        return d;\n    }\n\n    public void setTotalBuckets(int totalBuckets) {\n        this.totalBuckets = totalBuckets;\n    }\n\n    public int getTotalBuckets() {\n        return totalBuckets;\n    }","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/MyCATApache/Mycat-Server/blob/65f8d8beb752f935752f2a0eec0ab017facab9ef/src/main/java/io/mycat/route/function/PartitionByJumpConsistentHash.java#L31-L67","documentation":"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.","triggerScenarios":"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.","commonSituations":"Typo like count=-1 or an arithmetic expression yielding a negative count; automated config generation producing negative values; confusing partitionCount with a delta value.","solutions":["Set the buckets/partitionCount property to a positive integer equal to the number of dataNodes.","Validate the parsed config value before init (assert >= 0).","Fix any generator/script that emits negative counts into rule.xml."],"exampleFix":"// before\n<property name=\"partitionCount\">-1</property>\n// after\n<property name=\"partitionCount\">8</property>","handlingStrategy":"validation","validationCode":"if (buckets < 0) throw new IllegalArgumentException(\"buckets must be >= 0, got \" + buckets);\n","typeGuard":null,"tryCatchPattern":"try {\n    int node = partitionByJumpConsistentHash.calculate(columnValue);\n} catch (IllegalArgumentException e) {\n    // configuration bug: fix partitionCount before retrying\n}","preventionTips":["Schema-validate rule.xml numeric properties (non-negative) at startup","Never compute partitionCount from arithmetic that can go negative","Add a sanity assertion after parsing config"],"tags":["sharding","consistent-hash","configuration"],"backgroundTag":"value-out-of-range","analyzedSha":"65f8d8beb752f935752f2a0eec0ab017facab9ef","analyzedAt":"2026-09-11T00:12:21.696Z","contentChangedAt":"2026-09-11T00:12:21.696Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}