apache/seatunnel · error · IllegalArgumentException

bucketCount must be greater than zero, but was

Error message

bucketCount must be greater than zero, but was ${bucketCount}

What it means

HashUtils.checkBucketCount validates that a bucket count is strictly positive before computing a bucket index via modulo. A count <= 0 throws IllegalArgumentException with the offending value, since modulo by zero or negative buckets is meaningless.

Solutions

1. Ensure bucketCount is at least 1 before calling bucketIndex (e.g. Math.max(1, configuredCount))
2. Fix the upstream computation/config that produced 0 or a negative value
3. If derived from a config option, add a validation rule that rejects values < 1 at option-parsing time

Example fix

// before
int idx = HashUtils.bucketIndex(hash, bucketCount); // bucketCount may be 0
// after
int idx = HashUtils.bucketIndex(hash, Math.max(1, bucketCount));

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

static int safeBucketCount(int n) { return Math.max(1, n); }

try { return HashUtils.bucketIndex(hash, bucketCount); } catch (IllegalArgumentException e) { return HashUtils.bucketIndex(hash, 1); }

When it happens

Trigger: Calling HashUtils.bucketIndex(...) (or checkBucketCount directly) with bucketCount <= 0 — e.g. a config option like bucket count resolved to 0 by a misparsed/empty config value.

Common situations: Connector config where the bucket/parallelism option was computed as 0 (e.g. an empty list size or a division result) and passed into hashing; off-by-one in code computing bucket count dynamically.

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

• Already an MDCStream
• Already an MDCSupplier
• COMMON_ILLEGAL_ARGUMENT
• error handler must be between 0 and , but was
• Illegal format [ ]

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/ade0dba60928968d. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-common/src/main/java/org/apache/seatunnel/common/utils/HashUtils.java:75

     * {@code int} because it is smaller than {@code bucketCount}.
     *
     * <p>This is a distinct mapping from the {@code int} overload rather than a widening of it: a
     * 64-bit hash and its truncation to 32 bits generally land in different buckets, so a call site
     * must not be switched between the two overloads.
     *
     * @param hash any 64-bit hash, including negative values and {@link Long#MIN_VALUE}
     * @param bucketCount the number of buckets, must be greater than zero
     * @return a bucket index in {@code [0, bucketCount)}
     * @throws IllegalArgumentException if {@code bucketCount} is not greater than zero
     */
    public static int bucketIndex(long hash, int bucketCount) {
        checkBucketCount(bucketCount);
        return (int) ((hash & Long.MAX_VALUE) % bucketCount);
    }

    private static void checkBucketCount(int bucketCount) {
        if (bucketCount <= 0) {
            throw new IllegalArgumentException(
                    "bucketCount must be greater than zero, but was " + bucketCount);
        }
    }
}

View on GitHub (pinned to cf67b549a7)