{"record":{"id":"7a93e0739cf7e777","repo":"apache/beam","slug":"orderby-field-path-was-malformed","errorCode":null,"errorMessage":"OrderBy field path was malformed","messagePattern":"OrderBy field path was malformed","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/QueryUtils.java","lineNumber":181,"sourceCode":"    private static final String QUOTED_NAME_REGEX_STRING = \"(`(?:[^`\\\\\\\\]|(?:\\\\\\\\.))+`)\";\n    // After each segment follows a dot and more characters, or the end of the string.\n    private static final Pattern FIELD_PATH_SEGMENT_REGEX =\n        Pattern.compile(\n            String.format(\n                \"(?:%s|%s)(\\\\..+|$)\", UNQUOTED_NAME_REGEX_STRING, QUOTED_NAME_REGEX_STRING),\n            Pattern.DOTALL);\n\n    public static OrderByFieldPath fromString(String fieldPath) {\n      if (fieldPath.isEmpty()) {\n        throw new IllegalArgumentException(\"Could not resolve empty field path\");\n      }\n      String originalString = fieldPath;\n      List<String> segments = new ArrayList<>();\n      while (!fieldPath.isEmpty()) {\n        Matcher segmentMatcher = FIELD_PATH_SEGMENT_REGEX.matcher(fieldPath);\n        boolean foundMatch = segmentMatcher.lookingAt();\n        if (!foundMatch) {\n          throw new IllegalArgumentException(\"OrderBy field path was malformed\");\n        }\n        String fieldName;\n        if ((fieldName = segmentMatcher.group(1)) != null) {\n          segments.add(fieldName);\n        } else if ((fieldName = segmentMatcher.group(2)) != null) {\n          String unescaped = unescapeFieldName(fieldName.substring(1, fieldName.length() - 1));\n          segments.add(unescaped);\n        } else {\n          throw new IllegalArgumentException(\"OrderBy field path was malformed\");\n        }\n        fieldPath = fieldPath.substring(fieldName.length());\n        // Due to the regex, any non-empty fieldPath will have a dot before the next nested field.\n        if (fieldPath.startsWith(\".\")) {\n          fieldPath = fieldPath.substring(1);\n        }\n      }\n      return new OrderByFieldPath(originalString, ImmutableList.copyOf(segments));\n    }","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/QueryUtils.java#L163-L199","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Quote segments with special characters using backticks: `weird.field`.sub","Validate the path with the FIELD_PATH_SEGMENT_REGEX before calling fromString"],"exampleFix":"// before\nOrderByFieldPath.fromString(\"user..email\");\n// after\nOrderByFieldPath.fromString(\"user.email\");","handlingStrategy":"validation","validationCode":"Pattern SEGMENT = Pattern.compile(\"(?:[A-Za-z_][A-Za-z0-9_-]*|`(?:[^`\\\\\\\\]|\\\\\\\\.)+`)(?:\\\\..+|$)\", Pattern.DOTALL);\npublic static boolean isValidFieldPath(String p) {\n  if (p == null || p.isEmpty()) return false;\n  java.util.regex.Matcher m = SEGMENT.matcher(p);\n  while (!p.isEmpty()) {\n    if (!m.reset(p).lookingAt()) return false;\n    p = p.substring(m.end());\n    if (p.startsWith(\".\")) p = p.substring(1);\n  }\n  return true;\n}","typeGuard":null,"tryCatchPattern":"try {\n  OrderByFieldPath p = OrderByFieldPath.fromString(path);\n} catch (IllegalArgumentException e) {\n  throw new IllegalArgumentException(\"Malformed order-by path '\" + path + \"': use dot-separated segments, backtick-quote segments with special characters\", e);\n}","preventionTips":["Backtick-quote any segment containing characters outside [A-Za-z0-9_-]","Never concatenate field path strings without validating delimiters","Keep a shared helper that validates field paths before they reach query builders"],"tags":["java","apache-beam","firestore","field-path","malformed-input"],"backgroundTag":"invalid-argument-format","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}