MyCATApache/Mycat-Server · error · IllegalArgumentException

illegal hex-string

Error message

illegal hex-string: {hexString}

What it means

ParseString.hexString2Bytes converts a hexadecimal string to bytes, validating each nibble against 0-9a-fA-F. When any character is outside the hex alphabet, it throws IllegalArgumentException('illegal hex-string: ...') with the offending substring. Note this is a RuntimeException, not SQLNonTransientException.

Solutions

1. Strip the '0x' prefix and any whitespace before passing the string
2. Verify every character is [0-9a-fA-F] (and that the length is even) before calling
3. Correct the typo'd/corrupted hex value in the config or input

Example fix

// before
byte[] b = ParseString.hexString2Bytes("0x1A2F", 0, 6);
// after
String hex = "0x1A2F".replaceFirst("^0x","").trim();
if (!hex.matches("[0-9a-fA-F]+") || hex.length()%2!=0) throw new IllegalArgumentException("bad hex");
byte[] b = ParseString.hexString2Bytes(hex, 0, hex.length());

void assertHex(String s) {
    String h = s.replaceFirst("(?i)^0x","").trim();
    if (!h.matches("[0-9a-fA-F]+") || h.length()%2!=0)
        throw new IllegalArgumentException("illegal hex-string: " + s);
}

boolean isHexString(String s) {
    return s != null && s.replaceFirst("(?i)^0x","").matches("[0-9a-fA-F]+");
}

try { byte[] b = ParseString.hexString2Bytes(hex, 0, hex.length()); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("illegal hex-string")) { sanitizeAndRetry(e.getMessage()); } }

When it happens

Trigger: Calling hexString2Bytes (public) with a string containing a non-hex character at/after the given offset — e.g. '0x1G', 'zz', a string with 0x prefix not stripped, whitespace, or odd characters embedded in hex literals used by rule/config parsing.

Common situations: Hex literals in sharding rule config that include the '0x' prefix; corrupted/typo'd hex values; copying hex strings with trailing spaces or newlines; binary data pasted with non-hex characters.

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

• illegal hex-string
• clusterId and zkURL and myid must not be null or empty!
• columnValue: Please check if the format satisfied.
• columnValue: Please check if the format satisfied.
• columnValue: Please check if the format satisfied.

AI-assisted analysis of MyCATApache/Mycat-Server@65f8d8beb7 (2026-09-11). Data as JSON: /api/errors/3d37177237e74f68. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/io/mycat/route/parser/util/ParseString.java:108

                break;
            case 'c':
            case 'C':
                b = 0xc0;
                break;
            case 'd':
            case 'D':
                b = 0xd0;
                break;
            case 'e':
            case 'E':
                b = 0xe0;
                break;
            case 'f':
            case 'F':
                b = 0xf0;
                break;
            default:
                throw new IllegalArgumentException("illegal hex-string: " + new String(hexString, offset, length));
            }
            switch (low) {
            case '0':
                break;
            case '1':
                b += 1;
                break;
            case '2':
                b += 2;
                break;
            case '3':
                b += 3;
                break;
            case '4':
                b += 4;
                break;
            case '5':
                b += 5;

View on GitHub (pinned to 65f8d8beb7)