apache/beam · error · IllegalArgumentException

illegal unicode escape sequence

Error message

illegal unicode escape sequence

What it means

unescapeFieldName() handles \u (4 hex digits) and \U (8 hex digits) unicode escapes; if fewer than the required digits remain after the u/U it throws this IllegalArgumentException. The unicode escape is truncated so the quoted identifier cannot be decoded.

Source

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

              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)));
              i += 8;
              break;
            default:
              throw new IllegalArgumentException("illegal escape");
          }
        }
      }
      return buf.toString();

View on GitHub (pinned to 12126d8942)

Solutions

1. Supply all required hex digits (4 for \u, 8 for \U)
2. Use literal UTF-8 characters in the field name instead of escapes where possible
3. Validate the full escape sequence exists before parsing the field path

Example fix

// before
OrderByFieldPath.fromString("doc.`caf\\u0`"); // truncated unicode escape
// after
OrderByFieldPath.fromString("doc.`caf\\u00e9`");

public static boolean hasCompleteUnicodeEscapes(String s) {
  java.util.regex.Matcher m4 = Pattern.compile("\\\\u([0-9A-Fa-f]{0,4})").matcher(s);
  while (m4.find()) if (m4.group(1).length() < 4) return false;
  java.util.regex.Matcher m8 = Pattern.compile("\\\\U([0-9A-Fa-f]{0,8})").matcher(s);
  while (m8.find()) if (m8.group(1).length() < 8) return false;
  return true;
}

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

When it happens

Trigger: A quoted identifier containing \u with fewer than 4 hex digits remaining (e.g. `caf\u0`) or \U with fewer than 8 (e.g. `\U0001F60` at end of segment).

Common situations: Emoji/special-character field names encoded with unicode escapes that got truncated by string limits, logging redaction, or manual editing of config.

Related errors

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

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