apache/seatunnel · error · IllegalArgumentException

String range split requires fixed-length ASCII boundaries

Error message

String range split requires fixed-length ASCII boundaries

What it means

AsciiStringRangeSplitter.split computes numeric splits over string range boundaries by treating them as fixed-length ASCII values. Both boundaries must have exactly the same length; otherwise positional numeric splitting is impossible, so it throws IllegalArgumentException with this message.

Solutions

Use boundaries of equal length (e.g. pad the shorter one with low-value characters like 'A' or '0' consistent with your data).
Choose a different split key (numeric or fixed-length CHAR column).
Reduce the range so both ends share a fixed prefix length, or fall back to a single split for that table.

Example fix

// before
splitter.split("A", "ABC");
// after
splitter.split("AAA", "ABC");

Defensive patterns

Strategy: validation

Validate before calling

if (left == null || right == null || left.length() != right.length()) {
  throw new IllegalArgumentException("boundaries must be equal-length strings");
}

Prevention

Pad boundaries to equal length before splitting
Prefer numeric or fixed-length CHAR columns as split keys
Clamp ranges to a common fixed prefix length

When it happens

Trigger: Calling split(left, right) where left.length() != right.length(), e.g. split key range from 'A' to 'ABC', typically derived from query-based or string-column split boundaries.

Common situations: String split columns with variable-length data (names, codes) whose min/max differ in length; manually specifying string split ranges in source config.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/source/AsciiStringRangeSplitter.java:39

final class AsciiStringRangeSplitter {

    private static final int FIRST_PRINTABLE_ASCII = 32;
    private static final int LAST_PRINTABLE_ASCII = 126;
    private static final int RADIX = LAST_PRINTABLE_ASCII - FIRST_PRINTABLE_ASCII + 1;

    private AsciiStringRangeSplitter() {}

    // This mapping is order-preserving only for fixed-length printable ASCII strings under a
    // binary collation. Other shapes must be rejected and handled by hash or single splitting.
    static String[] split(String left, String right, int expectSliceNumber) {
        if (left == null || right == null) {
            throw new IllegalArgumentException("String range boundary cannot be null");
        }
        validateRangeBoundary(left, "left");
        validateRangeBoundary(right, "right");
        if (left.length() != right.length()) {
            throw new IllegalArgumentException(
                    "String range split requires fixed-length ASCII boundaries");
        }
        if (left.equals(right)) {
            return new String[] {left, right};
        }
        if (left.compareTo(right) > 0) {
            throw new IllegalArgumentException(
                    String.format(
                            "String range left boundary [%s] must not be greater than right boundary [%s]",
                            left, right));
        }

        BigInteger[] splitValues =
                splitBigInteger(
                        stringToBigInteger(left), stringToBigInteger(right), expectSliceNumber);
        String[] result = new String[splitValues.length];
        result[0] = left;
        result[splitValues.length - 1] = right;

View on GitHub (pinned to cf67b549a7)