Setting a number of Storage API streams is only supported…

Error message

Setting a number of Storage API streams is only supported when using STORAGE_WRITE_API

What it means

Configuring a fixed number of Storage API write streams is only supported for the STORAGE_WRITE_API method. When STORAGE_API_AT_LEAST_ONCE is selected, the write path does not use a fixed stream pool, so any configured stream count is ignored and this warning is logged.

Solutions

Remove withStorageApiNumStreams(...) when using STORAGE_API_AT_LEAST_ONCE
Switch back to Method.STORAGE_WRITE_API if a fixed stream count is genuinely needed
Use withAutoSharding() to control parallelism in at-least-once mode instead

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

if (method == Method.STORAGE_API_AT_LEAST_ONCE && storageApiNumStreams != 0) { /* remove withStorageApiNumStreams */ }

Prevention

Treat numStorageWriteApiStreams as STORAGE_WRITE_API-only
Audit options after migrating between Storage API write modes
Prefer auto-sharding for at-least-once parallelism control

When it happens

Trigger: Setting withStorageApiNumStreams(n) (or the numStorageWriteApiStreams option) while the write method is Method.STORAGE_API_AT_LEAST_ONCE.

Common situations: Pipelines migrated from STORAGE_WRITE_API to at-least-once mode for lower cost/complexity, keeping the stream-count tuning from the previous method.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

            "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) {
          LOG.error("The Storage API sink does not support the WRITE_TRUNCATE write disposition.");
        }
        Map<String, String> bigLakeConfiguration = getBigLakeConfiguration();
        if (bigLakeConfiguration != null) {
          checkArgument(
              Arrays.stream(new String[] {CONNECTION_ID, STORAGE_URI})

View on GitHub (pinned to 12126d8942)