Setting the number of Storage API streams is only…

Error message

Setting the number of Storage API streams is only applicable to an unbounded PCollection.

What it means

The number of Storage API write streams (numStorageWriteApiStreams) only makes sense for a streaming, unbounded write where Beam must decide how many concurrent streams to open. For a bounded PCollection the stream count is meaningless, so the value is ignored with this warning.

Solutions

Remove withStorageApiNumStreams(...) from the bounded write
Confirm the source is meant to be unbounded; if it is, investigate why the pipeline sees it as bounded
Rely on default parallelism for bounded writes instead of fixed stream counts

Example fix

// before
BigQueryIO.writeTableRows().to(table).withMethod(Method.STORAGE_WRITE_API).withStorageApiNumStreams(5) // bounded input
// after
BigQueryIO.writeTableRows().to(table).withMethod(Method.STORAGE_WRITE_API) // stream count removed

Defensive patterns

Strategy: validation

Validate before calling

if (input.isBounded() == PCollection.IsBounded.BOUNDED && storageApiNumStreams != 0) { /* remove stream count */ }

Prevention

Set withStorageApiNumStreams only for unbounded STORAGE_WRITE_API writes
Parameterize streaming options so batch runs omit them
Verify source boundedness after pipeline refactors

When it happens

Trigger: Calling withStorageApiNumStreams(n) (getStorageApiNumStreams != 0) on a BigQueryIO write whose input PCollection is bounded.

Common situations: Shared sink-builder code reused between streaming and batch jobs, leaving a tuned stream count in the batch path.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

                method);
          }
        }
      } else { // PCollection is bounded
        checkArgument(
            getTriggeringFrequency() == null,
            "Triggering frequency is only applicable to an unbounded PCollection.");
        checkArgument(
            !getAutoSharding(), "Auto-sharding is only applicable to an unbounded PCollection.");
        checkArgument(
            getNumFileShards() == 0,
            "Number of file shards is only applicable to an unbounded PCollection.");

        if (getStorageApiTriggeringFrequency(bqOptions) != null) {
          LOG.warn(
              "Setting the triggering frequency is only applicable to an unbounded PCollection.");
        }
        if (getStorageApiNumStreams(bqOptions) != 0) {
          LOG.warn(
              "Setting the number of Storage API streams is only applicable to an unbounded PCollection.");
        }
      }

      if (method == Method.STORAGE_API_AT_LEAST_ONCE && getStorageApiNumStreams(bqOptions) != 0) {
        LOG.warn(
            "Setting a number of Storage API streams is only supported when using STORAGE_WRITE_API");
      }

      if (method != Method.STORAGE_WRITE_API && method != Method.STORAGE_API_AT_LEAST_ONCE) {
        checkArgument(
            !getAutoSchemaUpdate(),
            "withAutoSchemaUpdate only supported when using STORAGE_WRITE_API or STORAGE_API_AT_LEAST_ONCE.");
        checkArgument(
            getBigLakeConfiguration() == null,
            "bigLakeConfiguration is only supported when using STORAGE_WRITE_API or STORAGE_API_AT_LEAST_ONCE.");
      } else {
        if (getWriteDisposition() == WriteDisposition.WRITE_TRUNCATE) {

View on GitHub (pinned to 12126d8942)