alibaba/DataX · error · RuntimeException

Failed to parse delimiter: `Hex str is empty`

Error message

Failed to parse delimiter: `Hex str is empty`

What it means

doriswriter's DelimiterParser.parse throws this when the configured column_separator starts with \x (case-insensitive) to declare a hex-encoded delimiter, but nothing follows the prefix — e.g. the literal string "\\x". After stripping the two-character prefix the remaining hex string is empty, which cannot encode any byte, so parsing aborts before stream load begins.

Source

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

import com.google.common.base.Strings;

import java.io.StringWriter;

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) {

View on GitHub (pinned to 80ec23d5c5)

Solutions

1. Complete the hex sequence: "\\x01" for SOH, "\\x1f", etc. — at least one hex byte must follow the prefix.
2. For a literal separator that merely starts with 'x', supply it without the backslash, or choose a different separator character.
3. Mind JSON escaping: in the job file write "\\\\x01" so Java sees "\\x01" if the value passes through another unescape layer.
4. Leave column_separator unset to use the writer's default delimiter.

Example fix

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

void checkDelimiter(String sp) {
  if (sp != null && sp.toUpperCase().startsWith("\\X")) {
    String hex = sp.substring(2);
    if (hex.isEmpty()) throw new IllegalArgumentException("hex delimiter missing digits after \\x");
  }
}

When it happens

Trigger: Setting loadProps.column_separator (or line_delimiter) to exactly "\\x" or "\\X" in the doriswriter job JSON. Values that are empty or null fall back to the default delimiter instead; only the bare hex prefix triggers this specific error.

Common situations: Intending to use a literal backslash-x as the separator and writing "\\x" unaware of the hex mode, truncating a hex delimiter like "\\x01" down to "\\x", or escaping mistakes in JSON where the intended hex digits end up stripped.

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 length error`
• 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/d7bf5b54e758b69b. Report an issue: GitHub.