apache/beam · error · IllegalArgumentException

illegal octal escape sequence

Error message

illegal octal escape sequence

What it means

unescapeFieldName() processes \0 through \3 octal escape sequences that must be followed by exactly two more characters forming a 3-digit octal code; if fewer than 3 characters remain it throws this IllegalArgumentException. The escape sequence is truncated, so the identifier is invalid.

Source

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

              break;
            case '\\':
              buf.append('\\');
              break;
            case '\'':
              buf.append('\'');
              break;
            case '"':
              buf.append('\"');
              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");
              }

View on GitHub (pinned to 12126d8942)

Solutions

1. Complete the octal escape with all three digits, e.g. \101 for 'A'
2. Remove the truncated escape if the character was not intended
3. Use \xNN or \uNNNN escapes instead for clarity and fixed length

Example fix

// before
OrderByFieldPath.fromString("doc.`a\\10`"); // truncated octal
// after
OrderByFieldPath.fromString("doc.`a\\101`");

public static boolean hasCompleteEscapes(String s) {
  for (int i = 0; i < s.length(); i++) {
    if (s.charAt(i) == '\\') {
      if (i + 1 >= s.length()) return false;
      char c = s.charAt(++i);
      int need = (c >= '0' && c <= '3') ? 2 : (c == 'x' || c == 'X') ? 2 : (c == 'u') ? 4 : (c == 'U') ? 8 : 0;
      if (i + need >= s.length()) return false;
      i += need;
    }
  }
  return true;
}

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

When it happens

Trigger: A quoted identifier ending with an incomplete octal escape, e.g. `a\10` (only 2 chars after the backslash) or `\0` at the very end of the segment.

Common situations: Programmatically generated identifiers with escape sequences cut off by length limits or string truncation; hand-written escapes where a digit was dropped.

Related errors

• quoted identifier cannot contain unescaped quote
• illegal trailing backslash
• illegal hex 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/3c0174e3325b7c19. Report an issue: GitHub.