{"record":{"id":"3eb71e41ed3a7d65","repo":"apache/beam","slug":"target-batch-overhead-s-must-be-between-0-and-1","errorCode":null,"errorMessage":"target_batch_overhead (%s) must be between 0 and 1","messagePattern":"target_batch_overhead \\((.+?)\\) must be between 0 and 1","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/util.py","lineNumber":525,"sourceCode":"  _MAX_GROWTH_FACTOR = 2\n\n  def __init__(\n      self,\n      min_batch_size=1,\n      max_batch_size=10000,\n      target_batch_overhead=.05,\n      target_batch_duration_secs=10,\n      target_batch_duration_secs_including_fixed_cost=None,\n      variance=0.25,\n      clock=time.time,\n      ignore_first_n_seen_per_batch_size=0,\n      record_metrics=True):\n    if min_batch_size > max_batch_size:\n      raise ValueError(\n          \"Minimum (%s) must not be greater than maximum (%s)\" %\n          (min_batch_size, max_batch_size))\n    if target_batch_overhead and not 0 < target_batch_overhead <= 1:\n      raise ValueError(\n          \"target_batch_overhead (%s) must be between 0 and 1\" %\n          (target_batch_overhead))\n    if target_batch_duration_secs and target_batch_duration_secs <= 0:\n      raise ValueError(\n          \"target_batch_duration_secs (%s) must be positive\" %\n          (target_batch_duration_secs))\n    if (target_batch_duration_secs_including_fixed_cost and\n        target_batch_duration_secs_including_fixed_cost <= 0):\n      raise ValueError(\n          \"target_batch_duration_secs_including_fixed_cost \"\n          \"(%s) must be positive\" %\n          (target_batch_duration_secs_including_fixed_cost))\n    if not (target_batch_overhead or target_batch_duration_secs or\n            target_batch_duration_secs_including_fixed_cost):\n      raise ValueError(\n          \"At least one of target_batch_overhead or \"\n          \"target_batch_duration_secs or \"\n          \"target_batch_duration_secs_including_fixed_cost must be positive.\")","sourceCodeStart":507,"sourceCodeEnd":543,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/util.py#L507-L543","documentation":"Raised in _BatchSizeEstimator (BatchElements) __init__ when target_batch_overhead is truthy but outside the (0, 1] interval. The overhead is a fraction of per-element cost to target (e.g. 0.05 for 5% overhead), so values like 0, negative numbers, or >1 are meaningless and rejected.","triggerScenarios":"BatchElements(target_batch_overhead=1.5), =-0.1, or =0 (0 also fails because the condition is 0 < x <= 1 when truthy).","commonSituations":"Confusing a fraction with a percentage (passing 50 instead of 0.05); reading the value from config as 'percent' and forgetting to divide by 100; typos like a doubled decimal.","solutions":["Express the overhead as a fraction in (0, 1], e.g. 0.02 for 2%.","If your config stores percentages, divide by 100 before passing: target_batch_overhead=overhead_pct / 100.0.","Validate the value at the call site and reject/normalize anything outside 0 < x <= 1 before constructing the transform."],"exampleFix":"// before\nbeam.BatchElements(target_batch_overhead=25)  # percent, not fraction\n\n// after\nbeam.BatchElements(target_batch_overhead=0.25)","handlingStrategy":"validation","validationCode":"if target_batch_overhead is not None and not 0 < target_batch_overhead <= 1:\n    raise ValueError('target_batch_overhead must be a fraction in (0, 1], e.g. 0.05 for 5%')","typeGuard":"def valid_overhead(x):\n    return x is None or (isinstance(x, (int, float)) and 0 < x <= 1)","tryCatchPattern":"try:\n    t = beam.BatchElements(target_batch_overhead=overhead)\nexcept ValueError:\n    logging.warning('target_batch_overhead=%s invalid; defaulting to 0.05', overhead)\n    t = beam.BatchElements(target_batch_overhead=0.05)","preventionTips":["Store overheads as fractions (0.05), never percentages, in config.","If the source is a percent field, divide by 100 at the boundary.","Add an assertion in the pipeline-options parsing layer: 0 < x <= 1."],"tags":["python","apache-beam","batchelements","config-validation"],"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"}