alibaba/DataX · error · RuntimeException

Failed to parse delimiter: `Hex str format error`

Error message

Failed to parse delimiter: `Hex str format error`

What it means

DelimiterParser.parse throws this when a hex-mode separator (prefix \x) contains characters outside 0-9/A-F after uppercasing. Each character is validated against the HEX_STRING alphabet; any non-hex character (g, z, punctuation, space) aborts parsing with 'Hex str format error'.

Source

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

    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();
        byte[] bytes = new byte[length];
        for (int i = 0; i < length; i++) {
            int pos = i * 2;
            bytes[i] = (byte) (charToByte(hexChars[pos]) << 4 | charToByte(hexChars[pos + 1]));

View on GitHub (pinned to 80ec23d5c5)

Solutions

1. Use only hex digits after \x: "\\x7c" encodes the pipe character '|'.
2. If the separator is plain ASCII, omit the \x prefix and write it directly, e.g. "|||".
3. Verify with printf/od that the intended byte maps to the two hex digits you wrote.
4. Remove stray whitespace or quotes around the value in the job JSON.

Example fix

// before
"loadProps": { "column_separator": "\\x||" }
// after
"loadProps": { "column_separator": "\\x7c\\x7c" } // or simply "||"

for (char c : sp.substring(2).toUpperCase().toCharArray())
  if ("0123456789ABCDEF".indexOf(c) == -1) throw new IllegalArgumentException("non-hex char in delimiter: " + sp);

boolean isValidHexDelimiter(String sp) { return sp.toUpperCase().startsWith("\\X") && sp.substring(2).matches("[0-9A-Fa-f]+"); }

When it happens

Trigger: Values like "\\xgg", "\\x0z", or "\\x0 " in loadProps.column_separator / line_delimiter. Even-length but non-hex content reaches this check, so e.g. "\\x||" (intended ASCII pipe with a stray prefix) also triggers it.

Common situations: Prefixing an ordinary printable separator with \x by mistake, mixing hex and ASCII thinking in one value, or case/typo issues like letter O written instead of zero.

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 length 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/b5b489a1469795fe. Report an issue: GitHub.