apache/beam · error · IllegalArgumentException

illegal escape

Error message

illegal escape

What it means

In unescapeFieldName, after a backslash the next character must be a recognized escape introducer ('u', 'U', or an octal digit). Any other character following the backslash throws IllegalArgumentException("illegal escape"). The library only supports this small escape grammar for encoded field names.

Solutions

  1. Remove or correct the unsupported escape character in the field name.
  2. Encode a literal backslash as a recognized escape (e.g. double it at the producing layer) so the decoder sees valid escape sequences.
  3. Use only the supported escapes: \uXXXX, \UXXXXXXXX, and octal sequences.
  4. Sanitize field names before writing them to Firestore so they never contain bare backslashes.

Example fix

// before
String field = "notes\tfirst"; // \t is not a supported escape
// after
String field = "notes_first"; // avoid the unsupported escape entirely
Defensive patterns

Strategy: validation

Validate before calling

// Java: reject backslashes not followed by a supported escape introducer
static boolean hasOnlySupportedEscapes(String name) {
  for (int i = 0; i < name.length(); i++) {
    if (name.charAt(i) == '\\') {
      if (i + 1 >= name.length()) return false;
      char c = name.charAt(i + 1);
      if (c != 'u' && c != 'U' && (c < '0' || c > '7')) return false;
    }
  }
  return true;
}

Try / catch

try {
  String decoded = QueryUtils.unescaped(fieldName);
} catch (IllegalArgumentException e) {
  LOG.error("Field name contains an illegal escape: %s", fieldName);
  throw new IllegalArgumentException("Sanitize field name before querying", e);
}

Prevention

When it happens

Trigger: A field name containing a backslash followed by an unsupported character, e.g. "my\nfield" or "a\b", when the name is decoded for a Firestore query.

Common situations: Field names written with Java-style escapes (\n, \t, \b) pasted into Firestore field names; Windows-style path-like field names with single backslashes; double-escaping mistakes where "\\" became a single backslash before parsing.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

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

              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();
    }

    private static int unescapeOctal(String str) {
      int ch = 0;
      for (int i = 0; i < str.length(); i++) {
        ch = 8 * ch + octalValue(str.charAt(i));
      }
      if (!Character.isValidCodePoint(ch)) {
        throw new IllegalArgumentException("illegal codepoint");
      }
      return ch;
    }

    private static int unescapeHex(String str) {

View on GitHub (pinned to 12126d8942)