apache/beam · error · IllegalArgumentException

targetBatchDurationSecs

Error message

targetBatchDurationSecs (%f) must be positive

What it means

BatchConfig.validate rejected targetBatchDurationSecs because it was <= 0. This config sets how long the BatchElements inserter may hold elements to reach a target batch size; a non-positive duration would stall batches forever, so build() fails fast during validation.

Solutions

1. Pass a positive duration in seconds (e.g. 0.1, 1.0)
2. Default the value when config is 0 or unset before building
3. Validate durations at config-load time

Example fix

// before
.withTargetBatchDuration(0)
// after
.withTargetBatchDuration(1.0)

if (!(targetBatchDurationSecs > 0)) throw new IllegalArgumentException("targetBatchDurationSecs must be > 0, got " + targetBatchDurationSecs);

try {
  return builder.withTargetBatchDuration(d);
} catch (IllegalArgumentException e) {
  LOG.error("Batch duration must be positive seconds", e); throw e;
}

When it happens

Trigger: Calling withTargetBatchDuration(x) with x <= 0 then build().

Common situations: Config value of 0 from an unset/zeroed settings field; seconds/milliseconds unit confusion yielding 0.0; typo passing a negative 'speedup' constant.

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 ( )
• targetBatchDurationSecsWithFixedCost
• targetBatchOverhead ( ) must be between 0 and 1
• 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/0a96ce01f377ca09. Report an issue: GitHub.

Appendix: source

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

      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));
        }
      }
    }
  }

  static class BatchSizeEstimator implements Serializable {
    private List<long[]> data = new ArrayList<>();
    private final BatchConfig config;
    private @Nullable Integer replayLastBatchSize = null; // null = no replay pending

View on GitHub (pinned to 12126d8942)