apache/beam · error · IllegalStateException

Failed to build query resumption token, field

Error message

Failed to build query resumption token, field '{fieldPath}' not found in doc with __name__ '{documentName}'

What it means

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.

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)

Example fix

// before
query.orderBy("metadata.updatedAt") // missing in some docs
// after
query.orderBy("__name__") // or backfill metadata.updatedAt in all docs

Defensive patterns

Strategy: try-catch

Validate before calling

// before the query: ensure ordering field exists
db.collection("books").whereExists(FieldPath.of("updatedAt")); // filter to docs having the field

Try / catch

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; } }

Prevention

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

When it happens

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

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

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/55d7d81d46b51ad1. 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:137

    @Override
    protected ServerStreamingCallable<RunQueryRequest, RunQueryResponse> getCallable(
        FirestoreStub firestoreStub) {
      return firestoreStub.runQueryCallable();
    }

    @Override
    protected RunQueryRequest setStartFrom(
        RunQueryRequest element, RunQueryResponse runQueryResponse) {
      StructuredQuery query = element.getStructuredQuery();
      StructuredQuery.Builder builder = query.toBuilder();
      builder.addAllOrderBy(QueryUtils.getImplicitOrderBy(query));
      Cursor.Builder cursor = Cursor.newBuilder().setBefore(false);
      for (Order order : builder.getOrderByList()) {
        Value value =
            QueryUtils.lookupDocumentValue(
                runQueryResponse.getDocument(), order.getField().getFieldPath());
        if (value == null) {
          throw new IllegalStateException(
              String.format(
                  "Failed to build query resumption token, field '%s' not found in doc with __name__ '%s'",
                  order.getField().getFieldPath(), runQueryResponse.getDocument().getName()));
        }
        cursor.addValues(value);
      }
      builder.setStartAt(cursor.build());
      return element.toBuilder().setStructuredQuery(builder.build()).build();
    }

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

    @Override
    protected @Nullable RunQueryResponse resumptionValue(
        @Nullable RunQueryResponse previousValue, RunQueryResponse nextValue) {

View on GitHub (pinned to 12126d8942)