apache/beam · error · IllegalArgumentException

Could not resolve empty field path

Error message

Could not resolve empty field path

What it means

QueryUtils.OrderByFieldPath.fromString() throws this IllegalArgumentException when asked to parse an empty string as a Firestore order-by field path. A field path must have at least one segment; an empty value cannot be resolved to any document field.

Source

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

      return null;
    }
    return findMapValue(segments, value.getMapValue().getFieldsMap());
  }

  private static class OrderByFieldPath implements Comparable<OrderByFieldPath> {

    private static final String UNQUOTED_NAME_REGEX_STRING = "([a-zA-Z_][a-zA-Z_0-9]*)";
    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");
        }

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure the order-by field path string is non-empty before calling fromString
2. If the sort field is optional, skip adding the OrderBy entirely instead of passing an empty string
3. Trim user/config input and reject blanks with a clear upstream validation error

Example fix

// before
String sortField = config.getOrDefault("sortField", "");
queryBuilder.addOrderBy(OrderByFieldPath.fromString(sortField));
// after
String sortField = config.getOrDefault("sortField", "").trim();
if (!sortField.isEmpty()) {
  queryBuilder.addOrderBy(OrderByFieldPath.fromString(sortField));
}

if (fieldPath == null || fieldPath.trim().isEmpty()) {
  throw new IllegalArgumentException("order-by field path must be a non-empty string");
}

try {
  OrderByFieldPath p = OrderByFieldPath.fromString(fieldPath);
} catch (IllegalArgumentException e) {
  LOG.warn("Invalid order-by field path '{}' : {}", fieldPath, e.getMessage());
}

When it happens

Trigger: Calling OrderByFieldPath.fromString("") or passing an empty/blank order-by field name into a Firestore query builder that constructs an OrderBy from a string.

Common situations: An ORDER BY / sort option is configured from user input or config where the field name is missing or trimmed to empty, e.g. an empty query parameter, YAML key, or CLI flag defaulting to "".

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• quoted identifier cannot be empty
• OrderBy field path was malformed
• 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/69a1782ec374ee6a. Report an issue: GitHub.