{"record":{"id":"bd0150c5c9043fb3","repo":"apache/beam","slug":"timeout-must-be-a-non-negative-number","errorCode":null,"errorMessage":"'timeout' must be a non-negative number","messagePattern":"'timeout' 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":80,"sourceCode":"    \"\"\"Put an item into the queue.\n\n    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","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/utils/byte_limited_queue.py#L62-L98","documentation":"ByteLimitedQueue.put validates that its timeout, when provided, is not negative. A negative timeout is meaningless for blocking semantics, so Beam raises ValueError immediately before touching the queue. The docstring explicitly documents ValueError for negative timeout.","triggerScenarios":"Calling byte_queue.put(item, item_bytes=..., block=True, timeout=-1) or passing a computed timeout that underflowed to a negative value.","commonSituations":"Computing a deadline as (deadline - now) after the deadline has passed; config files with negative timeout values; mixing units (ms vs seconds) producing negative remainders.","solutions":["Clamp the timeout before calling: timeout = max(0, timeout).","Pass timeout=None for infinite blocking if no deadline is intended.","Fix the deadline arithmetic that produced the negative value.","Validate user/config-supplied timeouts at load time."],"exampleFix":"// before\nq.put(item, item_bytes=n, timeout=deadline - time.time())\n// after\nq.put(item, item_bytes=n, timeout=max(0, deadline - time.time()))","handlingStrategy":"validation","validationCode":"if timeout is not None and timeout < 0:\n    raise ValueError('timeout must be >= 0 or None')","typeGuard":null,"tryCatchPattern":"try:\n    q.put(item, item_bytes=n, timeout=t)\nexcept ValueError:\n    q.put(item, item_bytes=n, timeout=None)","preventionTips":["Clamp computed timeouts with max(0, remaining)","Use None instead of negative values for 'wait forever'","Validate timeout config values at startup"],"tags":["python","apache-beam","queue","timeout"],"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"}