The setting of auto-sharding is ignored. It is only…

Error message

The setting of auto-sharding is ignored. It is only supported when writing an unbounded PCollection via FILE_LOADS, STREAMING_INSERTS or STORAGE_WRITE_API, but the method was {}.

What it means

Auto-sharding in BigQueryIO is only supported for unbounded PCollections written via FILE_LOADS, STREAMING_INSERTS, or STORAGE_WRITE_API. When a bounded input is written with STORAGE_API_AT_LEAST_ONCE, auto-sharding cannot apply, so the setting is ignored and this warning is logged.

Solutions

Remove the withAutoSharding() call for the bounded STORAGE_API_AT_LEAST_ONCE write
Switch the method to STORAGE_WRITE_API on an unbounded PCollection if auto-sharding is needed
Accept the warning; the flag simply has no effect for this combination

Example fix

// before
BigQueryIO.writeTableRows().to(table).withMethod(Method.STORAGE_API_AT_LEAST_ONCE).withAutoSharding() // bounded input
// after
BigQueryIO.writeTableRows().to(table).withMethod(Method.STORAGE_API_AT_LEAST_ONCE) // auto-sharding removed

Defensive patterns

Strategy: validation

Validate before calling

if (method == Method.STORAGE_API_AT_LEAST_ONCE && input.isBounded() == PCollection.IsBounded.BOUNDED && autoSharding) { /* remove withAutoSharding */ }

Prevention

Enable withAutoSharding only for unbounded PCollections
Separate streaming and batch sink builders to avoid inheriting auto-sharding
Check input boundedness when changing pipeline sources

When it happens

Trigger: Writing a bounded PCollection with method STORAGE_API_AT_LEAST_ONCE while getAutoSharding() is true (e.g. withAutoSharding() was called).

Common situations: Batch (bounded) pipelines that reused a streaming write configuration containing withAutoSharding(), or batch pipelines migrated to the Storage API at-least-once 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/21b401eaec94de04. 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:3889

        }
        if (method == Method.STORAGE_API_AT_LEAST_ONCE
            && getStorageApiTriggeringFrequency(bqOptions) != null) {
          LOG.warn(
              "Storage API triggering frequency option will be ignored is it can only be specified only "
                  + "when writing via STORAGE_WRITE_API, but the method was {}.",
              method);
        }
        if (getAutoSharding()) {
          if (method == Method.STORAGE_WRITE_API && getStorageApiNumStreams(bqOptions) > 0) {
            LOG.warn(
                "Both numStorageWriteApiStreams and auto-sharding options are set. Will default to auto-sharding."
                    + " To set a fixed number of streams, do not enable auto-sharding.");
          } else if (method == Method.FILE_LOADS && getNumFileShards() > 0) {
            LOG.warn(
                "Both numFileShards and auto-sharding options are set. Will default to auto-sharding."
                    + " To set a fixed number of file shards, do not enable auto-sharding.");
          } else if (method == Method.STORAGE_API_AT_LEAST_ONCE) {
            LOG.warn(
                "The setting of auto-sharding is ignored. It is only supported when writing an"
                    + " unbounded PCollection via FILE_LOADS, STREAMING_INSERTS or"
                    + " STORAGE_WRITE_API, but the method was {}.",
                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(

View on GitHub (pinned to 12126d8942)