alibaba/DataX · error · RuntimeException

Failed to parse delimiter: `Hex str length error`

Error message

Failed to parse delimiter: `Hex str length error`

What it means

DelimiterParser.parse throws this when a hex-mode separator (prefix \x) is followed by an odd number of hex characters. Hex encoding maps two characters to one byte, so lengths like 1 or 3 cannot be decoded and parsing fails with 'Hex str length error'.

Source

Thrown at doriswriter/src/main/java/com/alibaba/datax/plugin/writer/doriswriter/DelimiterParser.java:24

public class DelimiterParser {

    private static final String HEX_STRING = "0123456789ABCDEF";

    public static String parse(String sp, String dSp) throws RuntimeException {
        if ( Strings.isNullOrEmpty(sp)) {
            return dSp;
        }
        if (!sp.toUpperCase().startsWith("\\X")) {
            return sp;
        }
        String hexStr = sp.substring(2);
        // check hex str
        if (hexStr.isEmpty()) {
            throw new RuntimeException("Failed to parse delimiter: `Hex str is empty`");
        }
        if (hexStr.length() % 2 != 0) {
            throw new RuntimeException("Failed to parse delimiter: `Hex str length error`");
        }
        for (char hexChar : hexStr.toUpperCase().toCharArray()) {
            if (HEX_STRING.indexOf(hexChar) == -1) {
                throw new RuntimeException("Failed to parse delimiter: `Hex str format error`");
            }
        }
        // transform to separator
        StringWriter writer = new StringWriter();
        for (byte b : hexStrToBytes(hexStr)) {
            writer.append((char) b);
        }
        return writer.toString();
    }

    private static byte[] hexStrToBytes(String hexStr) {
        String upperHexStr = hexStr.toUpperCase();
        int length = upperHexStr.length() / 2;
        char[] hexChars = upperHexStr.toCharArray();

View on GitHub (pinned to 80ec23d5c5)

Solutions

1. Pad to an even number of hex digits: "\\x1" -> "\\x01".
2. Double-check each hex byte against an ASCII table when choosing control-character delimiters.
3. If a multi-character ASCII separator was intended, drop the \x prefix entirely (e.g. "|||") — non-hex values pass through unchanged.
4. Validate the delimiter with a quick hex-length check before deploying the job.

Example fix

// before
"loadProps": { "column_separator": "\\x1" }
// after
"loadProps": { "column_separator": "\\x01" }

String hex = sp.substring(2);
if (hex.length() % 2 != 0) throw new IllegalArgumentException("hex delimiter must have even digit count: " + sp);

boolean isEvenLengthHex(String sp) { return sp.toUpperCase().startsWith("\\X") && sp.substring(2).matches("[0-9A-Fa-f]*") && sp.substring(2).length() % 2 == 0; }

When it happens

Trigger: column_separator values such as "\\x1" (1 digit) or "\\xabc" (3 digits) in the doriswriter loadProps. The empty case is caught earlier; this fires only when the remaining substring's length % 2 != 0.

Common situations: Typos dropping one digit from a two-digit hex code ("\\x0" instead of "\\x0a"), copy-paste truncation, or intending three ASCII characters but accidentally including the \x prefix.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to parse delimiter: `Hex str is empty`
• Failed to parse delimiter: `Hex str format error`
• Failed to create row serializer, unsupported `format` from s
• load_url cannot be empty, or the host cannot connect.Please
• Unable to flush data to Doris: unknown result status.

AI-assisted analysis of alibaba/DataX@80ec23d5c5 (2026-08-14). Data as JSON: /api/errors/54abc0d89520901c. Report an issue: GitHub.