{"record":{"id":"ba71206fa3a3b069","repo":"apache/beam","slug":"at-least-one-of-target-batch-overhead-or-target-batch","errorCode":null,"errorMessage":"At least one of target_batch_overhead or target_batch_duration_secs or target_batch_duration_secs_including_fixed_cost must be positive.","messagePattern":"At least one of target_batch_overhead or target_batch_duration_secs or target_batch_duration_secs_including_fixed_cost must be positive\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/util.py","lineNumber":540,"sourceCode":"          \"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.\")\n    if ignore_first_n_seen_per_batch_size < 0:\n      raise ValueError(\n          'ignore_first_n_seen_per_batch_size (%s) must be non '\n          'negative' % (ignore_first_n_seen_per_batch_size))\n    self._min_batch_size = min_batch_size\n    self._max_batch_size = max_batch_size\n    self._target_batch_overhead = target_batch_overhead\n    self._target_batch_duration_secs = target_batch_duration_secs\n    self._target_batch_duration_secs_including_fixed_cost = (\n        target_batch_duration_secs_including_fixed_cost)\n    self._variance = variance\n    self._clock = clock\n    self._data = []\n    self._ignore_next_timing = False\n    self._ignore_first_n_seen_per_batch_size = (","sourceCodeStart":522,"sourceCodeEnd":558,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/util.py#L522-L558","documentation":"Raised in _BatchSizeEstimator (BatchElements) __init__ when none of the three tuning targets (target_batch_overhead, target_batch_duration_secs, target_batch_duration_secs_including_fixed_cost) is set to a positive value. The estimator has no objective to optimize toward, so the library refuses to construct it.","triggerScenarios":"Calling BatchElements(min_batch_size=..., max_batch_size=...) with all target_* parameters left at defaults (None/0/falsy).","commonSituations":"Constructing BatchElements with only size bounds, assuming that is enough; passing targets from config where all values were 0/'unset'; typo in a keyword name so the intended target silently stayed None.","solutions":["Supply at least one target, e.g. BatchElements(target_batch_overhead=0.05) or BatchElements(target_batch_duration_secs=1.0).","Check keyword spelling of the target_* parameters (a typo yields no error until this check).","If targets come from config, validate at load time that at least one is positive."],"exampleFix":"// before\nbeam.BatchElements(min_batch_size=1, max_batch_size=1000)\n\n// after\nbeam.BatchElements(min_batch_size=1, max_batch_size=1000,\n                   target_batch_overhead=0.05)","handlingStrategy":"validation","validationCode":"if not (target_batch_overhead or target_batch_duration_secs or target_batch_duration_secs_including_fixed_cost):\n    raise ValueError('BatchElements requires at least one positive target_batch_* parameter')","typeGuard":"def has_batch_target(**kw):\n    return any(kw.get(k) for k in ('target_batch_overhead',\n                                   'target_batch_duration_secs',\n                                   'target_batch_duration_secs_including_fixed_cost'))","tryCatchPattern":"try:\n    t = beam.BatchElements(min_batch_size=lo, max_batch_size=hi, **targets)\nexcept ValueError as e:\n    if 'At least one of' in str(e):\n        t = beam.BatchElements(min_batch_size=lo, max_batch_size=hi, target_batch_overhead=0.05)\n    else:\n        raise","preventionTips":["Wrap BatchElements in a project helper that supplies a default target (e.g. target_batch_overhead=0.05).","Double-check keyword spelling of target_* parameters; typos silently leave them unset.","Validate that config exposes at least one positive target before pipeline assembly."],"tags":["python","apache-beam","batchelements","missing-config"],"backgroundTag":"missing-required-argument","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"}