{"record":{"id":"ead1d533029513e1","repo":"apache/beam","slug":"item-bytes-must-be-a-non-negative-number","errorCode":null,"errorMessage":"'item_bytes' must be a non-negative number","messagePattern":"'item_bytes' must be a non-negative number","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/utils/byte_limited_queue.py","lineNumber":82,"sourceCode":"    If the queue is full, block until a free slot is available, unless `block`\n    is false or a timeout occurs.\n\n    Args:\n      item: The item to put into the queue.\n      item_bytes: The size of the item.\n      block: If True, block until space is available. If False, raise queue.Full\n        immediately if the queue is full.\n      timeout: If block is True, wait for at most `timeout` seconds. If None,\n        block indefinitely.\n\n    Raises:\n      ValueError: If timeout or item_bytes is negative.\n      queue.Full: If the queue is full and block is False or the timeout occurs.\n    \"\"\"\n    if timeout is not None and timeout < 0:\n      raise ValueError(\"'timeout' must be a non-negative number\")\n    if item_bytes < 0:\n      raise ValueError(\"'item_bytes' must be a non-negative number\")\n\n    with self._mutex:\n      if not self._waiting_writers and self._can_fit(item_bytes):\n        self._queue.append((item, item_bytes))\n        self._byte_size += item_bytes\n        self._not_empty.notify()\n        return\n\n      if not block:\n        raise queue.Full\n\n      # Reuse or create a condition\n      my_cond = (\n          self._condition_pool.pop()\n          if self._condition_pool else threading.Condition(self._mutex))\n\n      endtime = time.monotonic() + timeout if timeout is not None else None\n","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/utils/byte_limited_queue.py#L64-L100","documentation":"ByteLimitedQueue tracks capacity in bytes, so put() requires item_bytes to be a non-negative size estimate of the queued item. A negative size would corrupt the queue's byte accounting, so Beam raises ValueError before enqueuing.","triggerScenarios":"Calling byte_queue.put(item, item_bytes=-1), or passing a size computed as len(serialized) - offset where offset exceeded length.","commonSituations":"Encoding size computation bugs (negative deltas); uninitialized size variables defaulting oddly; off-by-one errors in record-size bookkeeping.","solutions":["Ensure the computed size is non-negative: item_bytes = max(0, computed_size).","Fix the size calculation (e.g. sys.getsizeof / len of encoded bytes).","Use item_bytes=0 for zero-cost sentinel items rather than negatives.","Add an assertion on computed sizes before calling put."],"exampleFix":"// before\nq.put(data, item_bytes=len(data) - header_len)\n// after\nq.put(data, item_bytes=max(0, len(data) - header_len))","handlingStrategy":"validation","validationCode":"if item_bytes < 0:\n    raise ValueError('item_bytes must be >= 0')","typeGuard":null,"tryCatchPattern":"try:\n    q.put(item, item_bytes=size)\nexcept ValueError:\n    q.put(item, item_bytes=max(0, size))","preventionTips":["Wrap size computation in max(0, ...)","Unit-test size-estimation helpers for edge cases","Use 0 for zero-cost sentinel items"],"tags":["python","apache-beam","queue"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}