{"record":{"id":"a4eba559ec828c54","repo":"apache/beam","slug":"max-batch-size-exceeded-nbatch-size-needs-to-be-equal-or","errorCode":null,"errorMessage":"Max batch size exceeded.%nBatch size needs to be equal or smaller than %d","messagePattern":"Max batch size exceeded\\.%nBatch size needs to be equal or smaller than (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/ml/src/main/java/org/apache/beam/sdk/extensions/ml/AnnotateImages.java","lineNumber":104,"sourceCode":"   * Instantiates the transform without side input.\n   *\n   * @param featureList list of features to be extracted from the image.\n   * @param batchSize desired size of request batches sent to Cloud Vision API. At least 1, at most\n   *     16.\n   * @param desiredRequestParallelism desiredRequestParallelism desired number of concurrent batched\n   *     requests.\n   */\n  public AnnotateImages(List<Feature> featureList, long batchSize, int desiredRequestParallelism) {\n    this.desiredRequestParallelism = desiredRequestParallelism;\n    contextSideInput = null;\n    this.featureList = featureList;\n    checkBatchSizeCorrectness(batchSize);\n    this.batchSize = batchSize;\n  }\n\n  private void checkBatchSizeCorrectness(long batchSize) {\n    if (batchSize > MAX_BATCH_SIZE) {\n      throw new IllegalArgumentException(\n          String.format(\n              \"Max batch size exceeded.%n\" + \"Batch size needs to be equal or smaller than %d\",\n              MAX_BATCH_SIZE));\n    } else if (batchSize < MIN_BATCH_SIZE) {\n      throw new IllegalArgumentException(\n          String.format(\n              \"Min batch size not reached.%n\" + \"Batch size needs to be larger or equal than %d\",\n              MIN_BATCH_SIZE));\n    }\n  }\n\n  /**\n   * Applies all necessary transforms to call the Vision API. In order to group requests into\n   * batches, we assign keys to the requests, as {@link GroupIntoBatches} works only on {@link KV}s.\n   */\n  @Override\n  public PCollection<List<AnnotateImageResponse>> expand(PCollection<T> input) {\n    ParDo.SingleOutput<T, AnnotateImageRequest> inputToRequestMapper;","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/ml/src/main/java/org/apache/beam/sdk/extensions/ml/AnnotateImages.java#L86-L122","documentation":"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.","triggerScenarios":"Building AnnotateImages with .withBatchSize(n) where n > 16 (MAX_BATCH_SIZE).","commonSituations":"Trying to maximize throughput by batching more images than Vision allows; copying a batch size from another API with higher limits.","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)."],"exampleFix":"// before\nAnnotateImages.newBuilder().setBatchSize(50).build();\n// after\nAnnotateImages.newBuilder().setBatchSize(16).build();","handlingStrategy":"validation","validationCode":"if (batchSize > 16) throw new IllegalArgumentException(\"Vision batch max is 16\");","typeGuard":null,"tryCatchPattern":"try { AnnotateImages.newBuilder().setBatchSize(n).build(); } catch (IllegalArgumentException e) { /* clamp to 16 */ }","preventionTips":["Cap configurable batch sizes with Math.min(n, 16)","Document the Vision API 16-image limit near config definitions","Validate pipeline options at startup"],"tags":["java","google-cloud-vision","batch-size","apache-beam"],"backgroundTag":"value-out-of-range","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}