{"record":{"id":"55d7d81d46b51ad1","repo":"apache/beam","slug":"failed-to-build-query-resumption-token-field-fieldpath-not","errorCode":null,"errorMessage":"Failed to build query resumption token, field '{fieldPath}' not found in doc with __name__ '{documentName}'","messagePattern":"Failed to build query resumption token, field '(.+?)' not found in doc with __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":137,"sourceCode":"    @Override\n    protected ServerStreamingCallable<RunQueryRequest, RunQueryResponse> getCallable(\n        FirestoreStub firestoreStub) {\n      return firestoreStub.runQueryCallable();\n    }\n\n    @Override\n    protected RunQueryRequest setStartFrom(\n        RunQueryRequest element, RunQueryResponse runQueryResponse) {\n      StructuredQuery query = element.getStructuredQuery();\n      StructuredQuery.Builder builder = query.toBuilder();\n      builder.addAllOrderBy(QueryUtils.getImplicitOrderBy(query));\n      Cursor.Builder cursor = Cursor.newBuilder().setBefore(false);\n      for (Order order : builder.getOrderByList()) {\n        Value value =\n            QueryUtils.lookupDocumentValue(\n                runQueryResponse.getDocument(), order.getField().getFieldPath());\n        if (value == null) {\n          throw new IllegalStateException(\n              String.format(\n                  \"Failed to build query resumption token, field '%s' not found in doc with __name__ '%s'\",\n                  order.getField().getFieldPath(), runQueryResponse.getDocument().getName()));\n        }\n        cursor.addValues(value);\n      }\n      builder.setStartAt(cursor.build());\n      return element.toBuilder().setStructuredQuery(builder.build()).build();\n    }\n\n    @Override\n    protected RunQueryRequest setReadTime(RunQueryRequest element, Instant readTime) {\n      return element.toBuilder().setReadTime(Timestamps.fromMillis(readTime.getMillis())).build();\n    }\n\n    @Override\n    protected @Nullable RunQueryResponse resumptionValue(\n        @Nullable RunQueryResponse previousValue, RunQueryResponse nextValue) {","sourceCodeStart":119,"sourceCodeEnd":155,"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#L119-L155","documentation":"After a RunQuery page returns, FirestoreV1ReadFn builds a resumption Cursor from the document's values for each ORDER BY field. QueryUtils.lookupDocumentValue returned null for one ordered field — the field is absent from the returned document — so the query cannot be safely resumed and this IllegalStateException is thrown.","triggerScenarios":"A query with orderBy(field) whose field path does not exist in some documents (e.g. missing optional field) combined with limit/pagination; the last doc on the page lacks the ordered field value.","commonSituations":"Ordering on an optional/nested field that only some documents contain; Firestore data written before the field existed; aggregation or nested field paths with typos.","solutions":["Ensure every document matching the query contains the ordered field, or backfill missing documents","Order by __name__ or a guaranteed-present field as a tiebreaker/fallback","Use Firestore's select/exists filters to exclude documents missing the field","Check the field path spelling (case-sensitive, dot-notation for nested fields)"],"exampleFix":"// before\nquery.orderBy(\"metadata.updatedAt\") // missing in some docs\n// after\nquery.orderBy(\"__name__\") // or backfill metadata.updatedAt in all docs","handlingStrategy":"try-catch","validationCode":"// before the query: ensure ordering field exists\ndb.collection(\"books\").whereExists(FieldPath.of(\"updatedAt\")); // filter to docs having the field","typeGuard":null,"tryCatchPattern":"try { /* run query with limit/orderBy */ } catch (IllegalStateException e) { if (e.getMessage().contains(\"Failed to build query resumption token\")) { // backfill missing field or restart from __name__ cursor } else { throw e; } }","preventionTips":["Order only on required fields that exist in every document","Add __name__ as a final tiebreaker in orderBy","Backfill optional fields used for ordering","Double-check nested field paths for typos"],"tags":["firestore","beam","pagination","resume-token"],"backgroundTag":"record-not-found","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"}