apache/beam · error · IllegalStateException

Unable to determine BatchGet resumption point. Most…

Error message

Unable to determine BatchGet resumption point. Most recently received doc __name__ '{docName}'

What it means

To resume a BatchGetDocuments read, FirestoreV1ReadFn finds the most recently received document name within the element's documents list to skip past it. If the received doc's __name__ cannot be located in the request's documents list (and it was never found as a missing doc either), the resumption point is indeterminable and this IllegalStateException is thrown.

Solutions

1. Upgrade to the latest Beam version — this area has had bug fixes in BatchGet resumption logic
2. Verify no custom code (DoFn overrides, fanout) mutates the BatchGetDocumentsRequest's documents list
3. As a workaround, avoid splitting batch element sizes below what the response references
4. Report with the doc __name__ from the message — it identifies which document failed the lookup

try { /* batchGet read */ } catch (IllegalStateException e) { if (e.getMessage().contains("Unable to determine BatchGet resumption point")) { // restart batch read from the beginning for this batch } else { throw e; } }

When it happens

Trigger: The BatchGetDocumentsResponse's found/missing document name is not present in the BatchGetDocumentsRequest documents list — e.g. request mutation mid-flight, duplicate restructuring of the element, or state desync between received docs and the pending request element.

Common situations: Checkpoint/resume after failure with a mutated or truncated documents list; connector bugs where foundName/missing don't match the request list order or content; very large batch requests that were re-split.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Failed to build query resumption token, field
• Input schema must contain document id field
• Unable to locate window for successful request
• A dataSourceConfiguration or dataSourceProviderFn has…
• A list of URNs for overriding transforms was provided but…

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

Appendix: source

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

      // we only scan until the second to last originalRequest. If the final element were to be
      // reached
      // the full request would be complete and we wouldn't be in this scenario
      int maxIndex = documentsList.size() - 2;
      for (int i = 0; i <= maxIndex; i++) {
        String docName = documentsList.get(i);
        if (docName.equals(missing) || docName.equals(foundName)) {
          startIndex = i;
          break;
        }
      }
      if (0 <= startIndex) {
        BatchGetDocumentsRequest.Builder builder = element.toBuilder().clearDocuments();
        documentsList.stream()
            .skip(startIndex + 1) // start from the next entry from the one we found
            .forEach(builder::addDocuments);
        return builder.build();
      }
      throw new IllegalStateException(
          String.format(
              "Unable to determine BatchGet resumption point. Most recently received doc __name__ '%s'",
              foundName != null ? foundName : missing));
    }

    @Override
    protected @Nullable BatchGetDocumentsResponse resumptionValue(
        @Nullable BatchGetDocumentsResponse previousValue, BatchGetDocumentsResponse newValue) {
      // No sense in resuming from an empty result.
      return newValue.getResultCase() == ResultCase.RESULT_NOT_SET ? previousValue : newValue;
    }

    @Override
    protected BatchGetDocumentsRequest setReadTime(
        BatchGetDocumentsRequest element, Instant readTime) {
      return element.toBuilder().setReadTime(Timestamps.fromMillis(readTime.getMillis())).build();
    }
  }

View on GitHub (pinned to 12126d8942)