apache/beam · error · IllegalArgumentException

Max batch size exceeded.%nBatch size needs to be equal or…

Error message

Max batch size exceeded.%nBatch size needs to be equal or smaller than %d

What it means

AnnotateImages enforces the Google Cloud Vision API batch limit. The constructor calls checkBatchSizeCorrectness, which throws IllegalArgumentException if the configured batchSize exceeds MAX_BATCH_SIZE (16). The API accepts at most 16 images per AnnotateImagesRequest.

Solutions

Set batchSize to 16 or less: .withBatchSize(16).
Remove the explicit batch size and use the default.
Cap the configured value programmatically with Math.min(batchSize, MAX_BATCH_SIZE).

Example fix

// before
AnnotateImages.newBuilder().setBatchSize(50).build();
// after
AnnotateImages.newBuilder().setBatchSize(16).build();

Defensive patterns

Strategy: validation

Validate before calling

if (batchSize > 16) throw new IllegalArgumentException("Vision batch max is 16");

Try / catch

try { AnnotateImages.newBuilder().setBatchSize(n).build(); } catch (IllegalArgumentException e) { /* clamp to 16 */ }

Prevention

Cap configurable batch sizes with Math.min(n, 16)
Document the Vision API 16-image limit near config definitions
Validate pipeline options at startup

When it happens

Trigger: Building AnnotateImages with .withBatchSize(n) where n > 16 (MAX_BATCH_SIZE).

Common situations: Trying to maximize throughput by batching more images than Vision allows; copying a batch size from another API with higher limits.

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/a4eba559ec828c54. Report an issue: GitHub.

Appendix: source

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

   * Instantiates the transform without side input.
   *
   * @param featureList list of features to be extracted from the image.
   * @param batchSize desired size of request batches sent to Cloud Vision API. At least 1, at most
   *     16.
   * @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;

View on GitHub (pinned to 12126d8942)