{"record":{"id":"f8295d4dd53d529f","repo":"apache/beam","slug":"invalid-firestore-document-name-documentname","errorCode":null,"errorMessage":"Invalid Firestore document name: {documentName}","messagePattern":"Invalid Firestore document name: (.+?)","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/FirestoreUtils.java","lineNumber":58,"sourceCode":"})\nfinal class FirestoreUtils {\n\n  private FirestoreUtils() {}\n\n  static String documentsRoot(String projectId, String databaseId) {\n    return String.format(\"projects/%s/databases/%s/documents\", projectId, databaseId);\n  }\n\n  static String documentPath(\n      String projectId, String databaseId, String collectionId, String documentId) {\n    return String.format(\n        \"%s/%s/%s\", documentsRoot(projectId, databaseId), collectionId, documentId);\n  }\n\n  static String documentIdFromName(String documentName) {\n    int lastSlash = documentName.lastIndexOf('/');\n    if (lastSlash < 0 || lastSlash == documentName.length() - 1) {\n      throw new IllegalArgumentException(\"Invalid Firestore document name: \" + documentName);\n    }\n    return documentName.substring(lastSlash + 1);\n  }\n\n  static Row documentToRow(Document document, Schema schema, @Nullable String documentIdField) {\n    Map<String, Object> values = new HashMap<>();\n    for (Map.Entry<String, Value> entry : document.getFieldsMap().entrySet()) {\n      values.put(entry.getKey(), valueToJava(entry.getValue()));\n    }\n    if (documentIdField != null && schema.hasField(documentIdField)) {\n      values.put(documentIdField, documentIdFromName(document.getName()));\n    }\n    return toRow(values, schema);\n  }\n\n  static Document rowToDocument(\n      Row row,\n      Schema schema,","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/FirestoreUtils.java#L40-L76","documentation":"FirestoreUtils.documentIdFromName extracts the document ID (the last path segment) from a full Firestore document name. It throws IllegalArgumentException when the name contains no '/' at all or ends with a '/', because in either case there is no valid document ID segment to extract.","triggerScenarios":"Calling documentIdFromName with a string like 'projects/p/databases/d/documents/col' (collection path, no document id) or with a plain document id like 'mydoc' (no slash). Called from documentToRow when mapping read documents to Rows with a documentIdField.","commonSituations":"Passing a collection path instead of a document path; building document names by string concatenation and leaving a trailing slash; querying a collection and accidentally using the collection name as the document name; empty or whitespace-only names after splitting on '/'.","solutions":["Pass a full document path with a non-empty final segment, e.g. projects/PROJECT/databases/DATABASE/documents/collection/docId","Strip trailing slashes from document names before calling the API","Validate with a regex like '^.+/.+$' (at least one slash and a non-empty segment after it) before calling","If you only have a collection path, append the specific document ID before conversion"],"exampleFix":"// before\nString name = \"projects/p/databases/d/documents/users\"; // collection path\nString id = FirestoreUtils.documentIdFromName(name); // throws\n// after\nString name = \"projects/p/databases/d/documents/users/user42\";\nString id = FirestoreUtils.documentIdFromName(name); // \"user42\"","handlingStrategy":"validation","validationCode":"if (documentName == null || !documentName.contains(\"/\") || documentName.endsWith(\"/\")) {\n  throw new IllegalArgumentException(\"Document name must have a final non-empty segment: \" + documentName);\n}\nString id = FirestoreUtils.documentIdFromName(documentName);","typeGuard":"static boolean isValidDocumentName(String name) {\n  return name != null && name.matches(\".+/.+\");\n}","tryCatchPattern":"try {\n  String id = FirestoreUtils.documentIdFromName(name);\n} catch (IllegalArgumentException e) {\n  log.error(\"Bad document name: {}\", name, e);\n}","preventionTips":["Always build names with documentPath() instead of manual string concatenation","Regex-check names (^.+/.+$) before parsing","Strip trailing slashes from user- or config-supplied paths"],"tags":["java","apache-beam","firestore","argument-validation"],"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-14T11:17:12.474Z"}