apache/beam · error · IllegalArgumentException

Min batch size not reached.%nBatch size needs to be larger…

Error message

Min batch size not reached.%nBatch size needs to be larger or equal than %d

What it means

AnnotateImages enforces a minimum batch size (MIN_BATCH_SIZE = 1). checkBatchSizeCorrectness throws IllegalArgumentException if batchSize is below MIN_BATCH_SIZE, because a non-positive batch would never send any image to the Vision API.

Solutions

Set batchSize to at least 1: .withBatchSize(1).
Clamp the computed value: Math.max(1, Math.min(batchSize, 16)).
Validate upstream pipeline options before constructing the transform.

Example fix

// before
AnnotateImages.newBuilder().setBatchSize(options.getBatchSize()).build(); // batchSize = 0
// after
AnnotateImages.newBuilder().setBatchSize(Math.max(1, options.getBatchSize())).build();

Defensive patterns

Strategy: validation

Validate before calling

if (batchSize < 1) throw new IllegalArgumentException("Batch size must be >= 1");

Prevention

Clamp computed batch sizes: Math.max(1, n)
Never default numeric options to 0
Validate options before constructing transforms

When it happens

Trigger: Building AnnotateImages with .withBatchSize(n) where n < 1 (zero or negative batch size).

Common situations: Computing the batch size dynamically and accidentally producing 0 or a negative value; misconfigured pipeline options yielding an unset/zero value.

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

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

Appendix: source

Thrown at sdks/java/extensions/ml/src/main/java/org/apache/beam/sdk/extensions/ml/AnnotateImages.java:109

   * @param desiredRequestParallelism desiredRequestParallelism desired number of concurrent batched
   *     requests.
   */
  public AnnotateImages(List<Feature> featureList, long batchSize, int desiredRequestParallelism) {
    this.desiredRequestParallelism = desiredRequestParallelism;
    contextSideInput = null;
    this.featureList = featureList;
    checkBatchSizeCorrectness(batchSize);
    this.batchSize = batchSize;
  }

  private void checkBatchSizeCorrectness(long batchSize) {
    if (batchSize > MAX_BATCH_SIZE) {
      throw new IllegalArgumentException(
          String.format(
              "Max batch size exceeded.%n" + "Batch size needs to be equal or smaller than %d",
              MAX_BATCH_SIZE));
    } else if (batchSize < MIN_BATCH_SIZE) {
      throw new IllegalArgumentException(
          String.format(
              "Min batch size not reached.%n" + "Batch size needs to be larger or equal than %d",
              MIN_BATCH_SIZE));
    }
  }

  /**
   * Applies all necessary transforms to call the Vision API. In order to group requests into
   * batches, we assign keys to the requests, as {@link GroupIntoBatches} works only on {@link KV}s.
   */
  @Override
  public PCollection<List<AnnotateImageResponse>> expand(PCollection<T> input) {
    ParDo.SingleOutput<T, AnnotateImageRequest> inputToRequestMapper;
    if (contextSideInput != null) {
      inputToRequestMapper =
          ParDo.of(new MapInputToRequest(contextSideInput)).withSideInputs(contextSideInput);
    } else {
      inputToRequestMapper = ParDo.of(new MapInputToRequest(null));

View on GitHub (pinned to 12126d8942)