{"record":{"id":"50644da26e322ec1","repo":"apache/beam","slug":"illegal-escape","errorCode":null,"errorMessage":"illegal escape","messagePattern":"illegal escape","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":348,"sourceCode":"              break;\n            case 'u':\n              i++;\n              if (i + 4 > fieldName.length()) {\n                throw new IllegalArgumentException(\"illegal unicode escape sequence\");\n              }\n              buf.appendCodePoint(unescapeHex(fieldName.substring(i, i + 4)));\n              i += 4;\n              break;\n            case 'U':\n              i++;\n              if (i + 8 > fieldName.length()) {\n                throw new IllegalArgumentException(\"illegal unicode escape sequence\");\n              }\n              buf.appendCodePoint(unescapeHex(fieldName.substring(i, i + 8)));\n              i += 8;\n              break;\n            default:\n              throw new IllegalArgumentException(\"illegal escape\");\n          }\n        }\n      }\n      return buf.toString();\n    }\n\n    private static int unescapeOctal(String str) {\n      int ch = 0;\n      for (int i = 0; i < str.length(); i++) {\n        ch = 8 * ch + octalValue(str.charAt(i));\n      }\n      if (!Character.isValidCodePoint(ch)) {\n        throw new IllegalArgumentException(\"illegal codepoint\");\n      }\n      return ch;\n    }\n\n    private static int unescapeHex(String str) {","sourceCodeStart":330,"sourceCodeEnd":366,"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#L330-L366","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove or correct the unsupported escape character in the field name.","Encode a literal backslash as a recognized escape (e.g. double it at the producing layer) so the decoder sees valid escape sequences.","Use only the supported escapes: \\uXXXX, \\UXXXXXXXX, and octal sequences.","Sanitize field names before writing them to Firestore so they never contain bare backslashes."],"exampleFix":"// before\nString field = \"notes\\tfirst\"; // \\t is not a supported escape\n// after\nString field = \"notes_first\"; // avoid the unsupported escape entirely","handlingStrategy":"validation","validationCode":"// Java: reject backslashes not followed by a supported escape introducer\nstatic boolean hasOnlySupportedEscapes(String name) {\n  for (int i = 0; i < name.length(); i++) {\n    if (name.charAt(i) == '\\\\') {\n      if (i + 1 >= name.length()) return false;\n      char c = name.charAt(i + 1);\n      if (c != 'u' && c != 'U' && (c < '0' || c > '7')) return false;\n    }\n  }\n  return true;\n}","typeGuard":null,"tryCatchPattern":"try {\n  String decoded = QueryUtils.unescaped(fieldName);\n} catch (IllegalArgumentException e) {\n  LOG.error(\"Field name contains an illegal escape: %s\", fieldName);\n  throw new IllegalArgumentException(\"Sanitize field name before querying\", e);\n}","preventionTips":["Do not put raw backslashes or Java-style escapes (\\n, \\t) into Firestore field names.","Escape field names with a single, library-owned escaping routine.","Sanitize user-supplied field names before writing them to Firestore."],"tags":["firestore","field-name","escaping","java","apache-beam"],"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-20T03:17:13.778Z"}