{"record":{"id":"325400ce04b9943f","repo":"apache/beam","slug":"targetbatchoverhead-f-must-be-between-0-and-1","errorCode":null,"errorMessage":"targetBatchOverhead (%f) must be between 0 and 1","messagePattern":"targetBatchOverhead \\((.+?)\\) must be between 0 and 1","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/BatchElements.java","lineNumber":248,"sourceCode":"      public Builder withVariance(double variance) {\n        this.variance = variance;\n        return this;\n      }\n\n      public BatchConfig build() {\n        validate();\n        return new BatchConfig(this);\n      }\n\n      private void validate() {\n        if (minBatchSize > maxBatchSize) {\n          throw new IllegalArgumentException(\n              String.format(\n                  \"Minimum (%d) must not be greater than maximum (%d)\",\n                  minBatchSize, maxBatchSize));\n        }\n        if (!(targetBatchOverhead > 0 && targetBatchOverhead <= 1)) {\n          throw new IllegalArgumentException(\n              String.format(\n                  \"targetBatchOverhead (%f) must be between 0 and 1\", targetBatchOverhead));\n        }\n        if (targetBatchDurationSecs <= 0) {\n          throw new IllegalArgumentException(\n              String.format(\n                  \"targetBatchDurationSecs (%f) must be positive\", targetBatchDurationSecs));\n        }\n        if (targetBatchDurationSecsWithFixedCost != -1\n            && targetBatchDurationSecsWithFixedCost <= 0) {\n          throw new IllegalArgumentException(\n              String.format(\n                  \"targetBatchDurationSecsWithFixedCost (%f) must be positive\",\n                  targetBatchDurationSecsWithFixedCost));\n        }\n      }\n    }\n  }","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/BatchElements.java#L230-L266","documentation":"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.","triggerScenarios":"Calling withTargetBatchOverhead(x) with x <= 0 or x > 1 (e.g. 0, negative, or 1.5) then build().","commonSituations":"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.","solutions":["Provide overhead as a fraction strictly between 0 and 1 (e.g. 0.2)","Validate/normalize config values (divide by 100 if a percent) before building","Omit the setting to use the default if unsure"],"exampleFix":"// before\n.withTargetBatchOverhead(20)\n// after\n.withTargetBatchOverhead(0.2)","handlingStrategy":"validation","validationCode":"if (!(targetBatchOverhead > 0 && targetBatchOverhead <= 1)) throw new IllegalArgumentException(\"targetBatchOverhead must be a fraction in (0,1], got \" + targetBatchOverhead);","typeGuard":null,"tryCatchPattern":"try {\n  return builder.withTargetBatchOverhead(overhead);\n} catch (IllegalArgumentException e) {\n  LOG.error(\"Bad overhead value; expecting 0<x<=1 fraction\", e); throw e;\n}","preventionTips":["Store overhead as a fraction (0,1], not a percentage","Normalize percent config values (/100) before building","Document units next to the config key"],"tags":["java","builder-validation","batching"],"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"}