{"record":{"id":"0be7627fea580e08","repo":"apache/beam","slug":"max-batch-weight-must-be-1-got-max-batch-weight","errorCode":null,"errorMessage":"max_batch_weight must be >= 1, got {max_batch_weight}","messagePattern":"max_batch_weight must be >= 1, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/util.py","lineNumber":1392,"sourceCode":"          min_batch_size=1,\n          max_batch_size=10,\n          max_batch_weight=100,\n          element_size_fn=lambda x: len(x['text']))\n  \"\"\"\n  def __init__(\n      self,\n      min_batch_size: int,\n      max_batch_size: int,\n      max_batch_weight: int,\n      element_size_fn: Optional[Callable[[Any], int]] = None):\n    if min_batch_size < 1:\n      raise ValueError(f'min_batch_size must be >= 1, got {min_batch_size}')\n    if max_batch_size < min_batch_size:\n      raise ValueError(\n          f'max_batch_size ({max_batch_size}) must be >= '\n          f'min_batch_size ({min_batch_size})')\n    if max_batch_weight < 1:\n      raise ValueError(f'max_batch_weight must be >= 1, got {max_batch_weight}')\n    if element_size_fn is not None and not callable(element_size_fn):\n      raise TypeError('element_size_fn must be callable')\n\n    self._min_batch_size = min_batch_size\n    self._max_batch_size = max_batch_size\n    self._max_batch_weight = max_batch_weight\n\n    # None means the DoFn will use its own _default_element_size method,\n    # which tries len() and warns once on TypeError before falling back to 1.\n    self._element_size_fn = element_size_fn\n\n  def expand(self, pcoll):\n    if pcoll.windowing.is_default():\n      return pcoll | ParDo(\n          _SortAndBatchElementsDoFn(\n              self._min_batch_size,\n              self._max_batch_size,\n              self._max_batch_weight,","sourceCodeStart":1374,"sourceCodeEnd":1410,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/util.py#L1374-L1410","documentation":"GroupIntoBatches parameters require max_batch_weight to be a positive integer (>= 1), since a batch carrying zero or negative weight would never close; the constructor raises ValueError with the provided value.","triggerScenarios":"Calling util.GroupIntoBatches with max_batch_weight=0 or negative — often a computed weight limit, a misparsed option, or a literal 0 intended as 'unlimited'.","commonSituations":"Treating 0 as 'no limit' (the API does not); weight computed from element_size_fn results that underflow; typos like max_batch_weight=-1 in tuning configs.","solutions":["Pass max_batch_weight >= 1 (estimate from element sizes times target batch size)","If you meant unlimited, omit/raise the value rather than passing 0","Validate the config value before constructing the transform"],"exampleFix":"// before\nutil.GroupIntoBatches(min_batch_size=1, max_batch_size=100, max_batch_weight=0)\n// after\nutil.GroupIntoBatches(min_batch_size=1, max_batch_size=100, max_batch_weight=1024)","handlingStrategy":"validation","validationCode":"if max_batch_weight < 1:\n    raise ValueError('max_batch_weight must be >= 1')","typeGuard":"def valid_weight(v): return isinstance(v, int) and v >= 1","tryCatchPattern":null,"preventionTips":["Never use 0 to mean 'unlimited' in this API","Compute weights from element sizes conservatively","Validate tuning knobs before pipeline construction"],"tags":["python","apache-beam","validation","constructor","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-14T21:17:11.552Z"}