apache/seatunnel · error · IllegalArgumentException

Only printable ASCII strings are supported for string range…

Error message

Only printable ASCII strings are supported for string range split, %s=[%s]

What it means

validateRangeBoundary enforces that every character of a string range boundary is a printable ASCII character (between FIRST_PRINTABLE_ASCII and LAST_PRINTABLE_ASCII). Non-printable or non-ASCII characters would break the BigInteger-based positional arithmetic over bytes, so the splitter throws IllegalArgumentException identifying the offending boundary and its value.

Solutions

1. Choose a split key with printable-ASCII-only values, or restrict the range to such values.
2. Sanitize/strip non-printable characters from boundaries before splitting.
3. Use a numeric or fixed-length ASCII column as the split key instead.
4. Fall back to a single (non-split) read for tables with non-ASCII key ranges.

static boolean isPrintableAscii(String s) {
  return s.chars().allMatch(c -> c >= 32 && c <= 126);
}

When it happens

Trigger: split() invoked with boundaries containing multi-byte characters (UTF-8 like 'é', CJK), control characters, whitespace below space (0x20), or DEL and above; validateRangeBoundary is called for both left and right boundaries.

Common situations: Split key columns containing localized text or emojis; boundaries copied from data with trailing control characters; Unicode data mistakenly chosen as split key.

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

• String range split requires fixed-length ASCII boundaries
• CONNECT_DATABASE_FAILED
• Currently, only support one split key
• Either table path or query must be specified in source…
• Invalid DuckDB JDBC url:

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/8bf2b0ccb37089b9. 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:123

    private static String bigIntegerToString(BigInteger value, int length) {
        char[] result = new char[length];
        BigInteger current = value;
        BigInteger radix = BigInteger.valueOf(RADIX);
        for (int i = length - 1; i >= 0; i--) {
            result[i] = (char) (current.mod(radix).intValue() + FIRST_PRINTABLE_ASCII);
            current = current.divide(radix);
        }
        if (current.compareTo(BigInteger.ZERO) > 0) {
            throw new IllegalArgumentException("Generated string boundary exceeds fixed length");
        }
        return new String(result);
    }

    private static void validateRangeBoundary(String value, String name) {
        for (int i = 0; i < value.length(); i++) {
            char ch = value.charAt(i);
            if (ch < FIRST_PRINTABLE_ASCII || ch > LAST_PRINTABLE_ASCII) {
                throw new IllegalArgumentException(
                        String.format(
                                "Only printable ASCII strings are supported for string range split, %s=[%s]",
                                name, value));
            }
        }
    }

    private static void validateLexicalOrder(String[] values) {
        for (int i = 1; i < values.length; i++) {
            if (values[i - 1].compareTo(values[i]) >= 0) {
                throw new IllegalArgumentException(
                        String.format(
                                "Generated string range boundary [%s] is not greater than previous boundary [%s]",
                                values[i], values[i - 1]));
            }
        }
    }
}

View on GitHub (pinned to cf67b549a7)