apache/beam · error · IllegalArgumentException

illegal hex escape sequence

Error message

illegal hex escape sequence

What it means

unescapeFieldName() handles \x and \X hex escape sequences requiring exactly two following hex digits; if fewer than two characters remain after the x it throws this IllegalArgumentException. The hex escape is incomplete and the quoted identifier is rejected.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/QueryUtils.java:326

              break;
            case '`':
              buf.append('`');
              break;
            case '0':
            case '1':
            case '2':
            case '3':
              if (i + 3 > fieldName.length()) {
                throw new IllegalArgumentException("illegal octal escape sequence");
              }
              buf.appendCodePoint(unescapeOctal(fieldName.substring(i, i + 3)));
              i += 3;
              break;
            case 'x':
            case 'X':
              i++;
              if (i + 2 > fieldName.length()) {
                throw new IllegalArgumentException("illegal hex escape sequence");
              }
              buf.appendCodePoint(unescapeHex(fieldName.substring(i, i + 2)));
              i += 2;
              break;
            case 'u':
              i++;
              if (i + 4 > fieldName.length()) {
                throw new IllegalArgumentException("illegal unicode escape sequence");
              }
              buf.appendCodePoint(unescapeHex(fieldName.substring(i, i + 4)));
              i += 4;
              break;
            case 'U':
              i++;
              if (i + 8 > fieldName.length()) {
                throw new IllegalArgumentException("illegal unicode escape sequence");
              }
              buf.appendCodePoint(unescapeHex(fieldName.substring(i, i + 8)));

View on GitHub (pinned to 12126d8942)

Solutions

1. Provide both hex digits, e.g. \x41 for 'A'
2. Remove the incomplete escape if not needed
3. Validate quoted identifiers contain complete escape sequences before parsing

Example fix

// before
OrderByFieldPath.fromString("doc.`f\\x4`"); // one hex digit
// after
OrderByFieldPath.fromString("doc.`f\\x41`");

public static boolean hasCompleteHexEscapes(String s) {
  java.util.regex.Matcher m = Pattern.compile("\\\\[xX]([0-9A-Fa-f]{0,2})").matcher(s);
  while (m.find()) {
    if (m.group(1).length() < 2) return false;
  }
  return true;
}

try {
  OrderByFieldPath p = OrderByFieldPath.fromString(path);
} catch (IllegalArgumentException e) {
  LOG.warn("Incomplete hex escape in '{}'", path);
}

When it happens

Trigger: A quoted identifier containing a truncated hex escape, e.g. `a\x4` or `\x` as the last characters of the segment content.

Common situations: Generated identifiers whose escape sequences were truncated by slicing/truncation, or typos dropping a hex digit when encoding special characters in field names.

Related errors

• quoted identifier cannot contain unescaped quote
• illegal trailing backslash
• illegal octal escape sequence
• illegal unicode escape sequence
• Could not resolve empty field path

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/f8048be7f1341dbc. Report an issue: GitHub.