apache/beam · error · RuntimeException

Bounded Source is not BigQueryStorageStreamSource, unable to

Error message

Bounded Source is not BigQueryStorageStreamSource, unable to read

What it means

Thrown in the Storage API streaming read path when the provided BoundedSource is not a BigQueryStorageStreamSource, so Beam cannot create a copy with the error-handling parse function. This is an internal invariant: the source passed to the reader was of the wrong type.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BigQueryIO.java:1985

          BadRecordRouter badRecordRouter) {
        this.rowTag = rowTag;
        this.parseFn = parseFn;
        this.badRecordRouter = badRecordRouter;
      }

      @ProcessElement
      public void processElement(
          @Element BoundedSource<T> boundedSource,
          MultiOutputReceiver outputReceiver,
          PipelineOptions options)
          throws Exception {
        ErrorHandlingParseFn<T> errorHandlingParseFn = new ErrorHandlingParseFn<T>(parseFn);
        BoundedSource<T> sourceWithErrorHandlingParseFn;
        if (boundedSource instanceof BigQueryStorageStreamSource) {
          sourceWithErrorHandlingParseFn =
              ((BigQueryStorageStreamSource<T>) boundedSource).fromExisting(errorHandlingParseFn);
        } else {
          throw new RuntimeException(
              "Bounded Source is not BigQueryStorageStreamSource, unable to read");
        }
        readSource(
            options,
            rowTag,
            outputReceiver,
            sourceWithErrorHandlingParseFn,
            errorHandlingParseFn,
            badRecordRouter);
      }
    }

    private PCollectionTuple createTupleForDirectRead(
        PCollection<String> jobIdTokenCollection,
        Coder<T> outputCoder,
        TupleTag<ReadStream> readStreamsTag,
        TupleTag<ReadSession> readSessionTag,
        TupleTag<String> tableSchemaTag) {

View on GitHub (pinned to 12126d8942)

Solutions

Ensure the read uses TypedRead.Method.DIRECT_READ/STORAGE_API so a BigQueryStorageStreamSource is produced
Use fromExisting()/from a source created by the same BigQueryIO version
Update Beam to a consistent version across pipeline construction and runner classpath

Defensive patterns

Strategy: type-guard

Type guard

boolean isStorageStreamSource(BoundedSource<?> s) {
  return s instanceof BigQueryStorageStreamSource;
}

Try / catch

if (!(boundedSource instanceof BigQueryStorageStreamSource)) {
  throw new IllegalStateException(
      "Expected BigQueryStorageStreamSource but got " + boundedSource.getClass().getName());
}

Prevention

Keep Beam versions consistent between pipeline code and runner classpath
Only feed sources produced by the Storage API read path into stream-source consumers
Pin the Beam version when using custom runners

When it happens

Trigger: BigQueryIO Storage API read path receives a BoundedSource from an unexpected origin (e.g. after a runner-specific source rewrite, test injection, or method mismatch) and the instanceof check fails.

Common situations: Custom runners or test harnesses substituting sources; mixing Storage API read settings with sources produced by the EXPORT method; Beam version upgrade changing source types.

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

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