apache/seatunnel · error · IllegalArgumentException

Illegal value of num

Error message

Illegal value of num

What it means

getTableKeyRanges validates that the requested number of key ranges for a table is positive; num <= 0 cannot produce a sane range partitioning (num==1 yields the full table range). Thrown as IllegalArgumentException before any range computation begins.

Solutions

1. Check the connector config that feeds the split/parallelism count and set it to >= 1
2. Fix the caller's computation to clamp to Math.max(1, computedRanges)
3. Validate user-supplied parallelism options before job submission
4. If this arises from internal math, log the inputs (tableId, num) and correct the divisor

Example fix

// before
int num = tableSizeBytes / splitSizeBytes; // 0 for tiny tables
List<KeyRange> ranges = TableKeyRangeUtils.getTableKeyRanges(tableId, num);
// after
int num = Math.max(1, (int) (tableSizeBytes / splitSizeBytes));
List<KeyRange> ranges = TableKeyRangeUtils.getTableKeyRanges(tableId, num);

int num = computeRangeCount(config);
if (num <= 0) {
    throw new IllegalArgumentException("Range count must be >= 1, got " + num + "; check parallelism config");
}
List<KeyRange> ranges = TableKeyRangeUtils.getTableKeyRanges(tableId, num);

try {
    ranges = TableKeyRangeUtils.getTableKeyRanges(tableId, num);
} catch (IllegalArgumentException e) {
    LOG.warn("Illegal num={}, falling back to single full-table range", num);
    ranges = TableKeyRangeUtils.getTableKeyRange(tableId);
}

When it happens

Trigger: Calling TableKeyRangeUtils.getTableKeyRanges(tableId, num) with num = 0 or negative — usually from a miscomputed parallelism/split-count derived from configuration (e.g. parallelism resolved to 0).

Common situations: A config option like scan.parallelism or increment.parallelism set to 0 or left unset and defaulted badly; arithmetic producing 0 ranges (e.g. splitting by byte size with tiny tables).

Related errors

• Already an MDCStream
• Already an MDCSupplier
• bucketCount must be greater than zero, but was
• Cannot deserialize TiDB DELETE CDC row because both value…
• Commit row has no matched prewrite row yet, hold it and…

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-tidb/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/tidb/source/utils/TableKeyRangeUtils.java:39

import org.tikv.common.util.KeyRangeUtils;
import org.tikv.kvproto.Coprocessor.KeyRange;

import java.math.BigInteger;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

/** Utils to obtain the keyRange of table. */
public class TableKeyRangeUtils {
    public static KeyRange getTableKeyRange(final long tableId) {
        return KeyRangeUtils.makeCoprocRange(
                RowKey.createMin(tableId).toByteString(),
                RowKey.createBeyondMax(tableId).toByteString());
    }

    public static List<KeyRange> getTableKeyRanges(final long tableId, final int num) {
        if (num <= 0) {
            throw new IllegalArgumentException("Illegal value of num");
        }

        if (num == 1) {
            return Collections.singletonList(getTableKeyRange(tableId));
        }

        final long delta =
                BigInteger.valueOf(Long.MAX_VALUE)
                        .subtract(BigInteger.valueOf(Long.MIN_VALUE + 1))
                        .divide(BigInteger.valueOf(num))
                        .longValueExact();
        final List<KeyRange> keyRanges = new ArrayList<>(num);
        for (int i = 0; i < num; i++) {
            final RowKey startKey =
                    (i == 0)
                            ? RowKey.createMin(tableId)
                            : RowKey.toRowKey(tableId, Long.MIN_VALUE + delta * i);
            final RowKey endKey =

View on GitHub (pinned to cf67b549a7)