apache/beam · error · IllegalArgumentException

OrderBy field path was malformed

Error message

OrderBy field path was malformed

What it means

fromString() matches the field path against FIELD_PATH_SEGMENT_REGEX segment by segment; if the remaining text does not start with a valid segment (unquoted name or backtick-quoted identifier), it throws this IllegalArgumentException. It means the field path string is syntactically invalid for Firestore ordering.

Source

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

    private static final String QUOTED_NAME_REGEX_STRING = "(`(?:[^`\\\\]|(?:\\\\.))+`)";
    // After each segment follows a dot and more characters, or the end of the string.
    private static final Pattern FIELD_PATH_SEGMENT_REGEX =
        Pattern.compile(
            String.format(
                "(?:%s|%s)(\\..+|$)", UNQUOTED_NAME_REGEX_STRING, QUOTED_NAME_REGEX_STRING),
            Pattern.DOTALL);

    public static OrderByFieldPath fromString(String fieldPath) {
      if (fieldPath.isEmpty()) {
        throw new IllegalArgumentException("Could not resolve empty field path");
      }
      String originalString = fieldPath;
      List<String> segments = new ArrayList<>();
      while (!fieldPath.isEmpty()) {
        Matcher segmentMatcher = FIELD_PATH_SEGMENT_REGEX.matcher(fieldPath);
        boolean foundMatch = segmentMatcher.lookingAt();
        if (!foundMatch) {
          throw new IllegalArgumentException("OrderBy field path was malformed");
        }
        String fieldName;
        if ((fieldName = segmentMatcher.group(1)) != null) {
          segments.add(fieldName);
        } else if ((fieldName = segmentMatcher.group(2)) != null) {
          String unescaped = unescapeFieldName(fieldName.substring(1, fieldName.length() - 1));
          segments.add(unescaped);
        } else {
          throw new IllegalArgumentException("OrderBy field path was malformed");
        }
        fieldPath = fieldPath.substring(fieldName.length());
        // Due to the regex, any non-empty fieldPath will have a dot before the next nested field.
        if (fieldPath.startsWith(".")) {
          fieldPath = fieldPath.substring(1);
        }
      }
      return new OrderByFieldPath(originalString, ImmutableList.copyOf(segments));
    }

View on GitHub (pinned to 12126d8942)

Solutions

1. Fix the field path string so every dot-separated segment is either an unquoted [A-Za-z_][A-Za-z0-9_-]* name or a backtick-quoted identifier
2. Quote segments with special characters using backticks: `weird.field`.sub
3. Validate the path with the FIELD_PATH_SEGMENT_REGEX before calling fromString

Example fix

// before
OrderByFieldPath.fromString("user..email");
// after
OrderByFieldPath.fromString("user.email");

Pattern SEGMENT = Pattern.compile("(?:[A-Za-z_][A-Za-z0-9_-]*|`(?:[^`\\\\]|\\\\.)+`)(?:\\..+|$)", Pattern.DOTALL);
public static boolean isValidFieldPath(String p) {
  if (p == null || p.isEmpty()) return false;
  java.util.regex.Matcher m = SEGMENT.matcher(p);
  while (!p.isEmpty()) {
    if (!m.reset(p).lookingAt()) return false;
    p = p.substring(m.end());
    if (p.startsWith(".")) p = p.substring(1);
  }
  return true;
}

try {
  OrderByFieldPath p = OrderByFieldPath.fromString(path);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Malformed order-by path '" + path + "': use dot-separated segments, backtick-quote segments with special characters", e);
}

When it happens

Trigger: Passing a field path with invalid characters for the next segment, e.g. "a..b", "a.`b" (unbalanced quote), "a. b" with illegal chars, or a path starting with an illegal character.

Common situations: Typo in sort field config (extra dots, stray backtick), programmatic string concatenation of field paths with leftover delimiters, or copying Firestore console paths that include invalid characters.

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.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

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