apache/beam · error · IllegalArgumentException

Invalid Firestore document name: {documentName}

Error message

Invalid Firestore document name: {documentName}

What it means

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.

Source

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

})
final class FirestoreUtils {

  private FirestoreUtils() {}

  static String documentsRoot(String projectId, String databaseId) {
    return String.format("projects/%s/databases/%s/documents", projectId, databaseId);
  }

  static String documentPath(
      String projectId, String databaseId, String collectionId, String documentId) {
    return String.format(
        "%s/%s/%s", documentsRoot(projectId, databaseId), collectionId, documentId);
  }

  static String documentIdFromName(String documentName) {
    int lastSlash = documentName.lastIndexOf('/');
    if (lastSlash < 0 || lastSlash == documentName.length() - 1) {
      throw new IllegalArgumentException("Invalid Firestore document name: " + documentName);
    }
    return documentName.substring(lastSlash + 1);
  }

  static Row documentToRow(Document document, Schema schema, @Nullable String documentIdField) {
    Map<String, Object> values = new HashMap<>();
    for (Map.Entry<String, Value> entry : document.getFieldsMap().entrySet()) {
      values.put(entry.getKey(), valueToJava(entry.getValue()));
    }
    if (documentIdField != null && schema.hasField(documentIdField)) {
      values.put(documentIdField, documentIdFromName(document.getName()));
    }
    return toRow(values, schema);
  }

  static Document rowToDocument(
      Row row,
      Schema schema,

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass a full document path with a non-empty final segment, e.g. projects/PROJECT/databases/DATABASE/documents/collection/docId
2. Strip trailing slashes from document names before calling the API
3. Validate with a regex like '^.+/.+$' (at least one slash and a non-empty segment after it) before calling
4. If you only have a collection path, append the specific document ID before conversion

Example fix

// before
String name = "projects/p/databases/d/documents/users"; // collection path
String id = FirestoreUtils.documentIdFromName(name); // throws
// after
String name = "projects/p/databases/d/documents/users/user42";
String id = FirestoreUtils.documentIdFromName(name); // "user42"

if (documentName == null || !documentName.contains("/") || documentName.endsWith("/")) {
  throw new IllegalArgumentException("Document name must have a final non-empty segment: " + documentName);
}
String id = FirestoreUtils.documentIdFromName(documentName);

static boolean isValidDocumentName(String name) {
  return name != null && name.matches(".+/.+");
}

try {
  String id = FirestoreUtils.documentIdFromName(name);
} catch (IllegalArgumentException e) {
  log.error("Bad document name: {}", name, e);
}

When it happens

Trigger: 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.

Common situations: 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 '/'.

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.

Related errors

• offset is negative:
• offset exceeds the buffer limit. offset: , limit:
• length is negative:
• offset + length exceeds the buffer limit. offset: , length:
• Unknown type of fn class %s

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