{"record":{"id":"9b1ed6e864a999f5","repo":"apache/beam","slug":"unable-to-determine-batchget-resumption-point-most-recently","errorCode":null,"errorMessage":"Unable to determine BatchGet resumption point. Most recently received doc __name__ '{docName}'","messagePattern":"Unable to determine BatchGet resumption point\\. Most recently received doc __name__ '(.+?)'","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/FirestoreV1ReadFn.java","lineNumber":478,"sourceCode":"      // we only scan until the second to last originalRequest. If the final element were to be\n      // reached\n      // the full request would be complete and we wouldn't be in this scenario\n      int maxIndex = documentsList.size() - 2;\n      for (int i = 0; i <= maxIndex; i++) {\n        String docName = documentsList.get(i);\n        if (docName.equals(missing) || docName.equals(foundName)) {\n          startIndex = i;\n          break;\n        }\n      }\n      if (0 <= startIndex) {\n        BatchGetDocumentsRequest.Builder builder = element.toBuilder().clearDocuments();\n        documentsList.stream()\n            .skip(startIndex + 1) // start from the next entry from the one we found\n            .forEach(builder::addDocuments);\n        return builder.build();\n      }\n      throw new IllegalStateException(\n          String.format(\n              \"Unable to determine BatchGet resumption point. Most recently received doc __name__ '%s'\",\n              foundName != null ? foundName : missing));\n    }\n\n    @Override\n    protected @Nullable BatchGetDocumentsResponse resumptionValue(\n        @Nullable BatchGetDocumentsResponse previousValue, BatchGetDocumentsResponse newValue) {\n      // No sense in resuming from an empty result.\n      return newValue.getResultCase() == ResultCase.RESULT_NOT_SET ? previousValue : newValue;\n    }\n\n    @Override\n    protected BatchGetDocumentsRequest setReadTime(\n        BatchGetDocumentsRequest element, Instant readTime) {\n      return element.toBuilder().setReadTime(Timestamps.fromMillis(readTime.getMillis())).build();\n    }\n  }","sourceCodeStart":460,"sourceCodeEnd":496,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/FirestoreV1ReadFn.java#L460-L496","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade to the latest Beam version — this area has had bug fixes in BatchGet resumption logic","Verify no custom code (DoFn overrides, fanout) mutates the BatchGetDocumentsRequest's documents list","As a workaround, avoid splitting batch element sizes below what the response references","Report with the doc __name__ from the message — it identifies which document failed the lookup"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"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; } }","preventionTips":["Keep the Beam SDK up to date (BatchGet resumption fixes land regularly)","Do not mutate BatchGetDocumentsRequest documents lists in custom code","Keep document name references and request lists in sync in any custom splitting"],"tags":["firestore","beam","batchget","resume-token"],"backgroundTag":"internal-invariant-violation","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"}