apache/beam · error · IllegalArgumentException

targetBatchOverhead ( ) must be between 0 and 1

Error message

targetBatchOverhead (%f) must be between 0 and 1

What it means

BatchConfig.validate rejected the configured targetBatchOverhead because it lies outside (0, 1]. This parameter bounds the fraction of per-batch overhead tolerated when sizing batches (BatchElements inserted by the runner's Globally batcher), so overhead fractions of 0 or >1 are meaningless and rejected at build() time.

Solutions

1. Provide overhead as a fraction strictly between 0 and 1 (e.g. 0.2)
2. Validate/normalize config values (divide by 100 if a percent) before building
3. Omit the setting to use the default if unsure

Example fix

// before
.withTargetBatchOverhead(20)
// after
.withTargetBatchOverhead(0.2)

if (!(targetBatchOverhead > 0 && targetBatchOverhead <= 1)) throw new IllegalArgumentException("targetBatchOverhead must be a fraction in (0,1], got " + targetBatchOverhead);

try {
  return builder.withTargetBatchOverhead(overhead);
} catch (IllegalArgumentException e) {
  LOG.error("Bad overhead value; expecting 0<x<=1 fraction", e); throw e;
}

When it happens

Trigger: Calling withTargetBatchOverhead(x) with x <= 0 or x > 1 (e.g. 0, negative, or 1.5) then build().

Common situations: Passing a percentage like 50 instead of 0.5; unit confusion (overhead given in ms or as 0-100 scale); config parsed from YAML/CLI without range checking.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Minimum ( ) must not be greater than maximum ( )
• targetBatchDurationSecs
• targetBatchDurationSecsWithFixedCost
• Batch size is too large! It should be smaller or equal than
• Column delimiter should be set if headers are present.

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/BatchElements.java:248

      public Builder withVariance(double variance) {
        this.variance = variance;
        return this;
      }

      public BatchConfig build() {
        validate();
        return new BatchConfig(this);
      }

      private void validate() {
        if (minBatchSize > maxBatchSize) {
          throw new IllegalArgumentException(
              String.format(
                  "Minimum (%d) must not be greater than maximum (%d)",
                  minBatchSize, maxBatchSize));
        }
        if (!(targetBatchOverhead > 0 && targetBatchOverhead <= 1)) {
          throw new IllegalArgumentException(
              String.format(
                  "targetBatchOverhead (%f) must be between 0 and 1", targetBatchOverhead));
        }
        if (targetBatchDurationSecs <= 0) {
          throw new IllegalArgumentException(
              String.format(
                  "targetBatchDurationSecs (%f) must be positive", targetBatchDurationSecs));
        }
        if (targetBatchDurationSecsWithFixedCost != -1
            && targetBatchDurationSecsWithFixedCost <= 0) {
          throw new IllegalArgumentException(
              String.format(
                  "targetBatchDurationSecsWithFixedCost (%f) must be positive",
                  targetBatchDurationSecsWithFixedCost));
        }
      }
    }
  }

View on GitHub (pinned to 12126d8942)