{"record":{"id":"147db690b9dc485f","repo":"openai/openai-python","slug":"send-queue-is-full-message-discarded","errorCode":null,"errorMessage":"send queue is full, message discarded","messagePattern":"send queue is full, message discarded","errorType":"exception","errorClass":"WebSocketQueueFullError","httpStatus":null,"severity":"error","filePath":"src/openai/_send_queue.py","lineNumber":36,"sourceCode":"    \"\"\"\n\n    def __init__(self, max_bytes: int = 1_048_576) -> None:\n        self._queue: list[tuple[str, int]] = []  # (data, byte_length)\n        self._bytes: int = 0\n        self._max_bytes = max_bytes\n        self._lock = threading.Lock()\n        self._flush_done: threading.Event | None = None\n\n    def enqueue(self, data: str) -> None:\n        \"\"\"Append *data* to the queue.\n\n        Raises :class:`WebSocketQueueFullError` if the message would\n        exceed the byte-size limit.\n        \"\"\"\n        byte_length = len(data.encode(\"utf-8\"))\n        with self._lock:\n            if self._bytes + byte_length > self._max_bytes:\n                raise WebSocketQueueFullError(\"send queue is full, message discarded\")\n            self._queue.append((data, byte_length))\n            self._bytes += byte_length\n\n    def flush_sync(self, send: typing.Callable[[str], object]) -> None:\n        \"\"\"Send every queued message via *send*.\n\n        If *send* raises, the failing message and all subsequent messages\n        are re-queued and the error is re-raised.\n        \"\"\"\n        while isinstance(pending := self._begin_flush(), threading.Event):\n            pending.wait()\n\n        try:\n            while pending:\n                data, byte_length = pending[0]\n                send(data)\n                with self._lock:\n                    pending.popleft()","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/openai/openai-python/blob/9917c6e28e66e90e1227b3d223c06a8c5441515a/src/openai/_send_queue.py#L18-L54","documentation":"The WebSocket send queue enforces a total byte limit; enqueue() raises WebSocketQueueFullError when adding a message would push the queued bytes over max_bytes. This bounds memory when messages are queued faster than the socket can flush them.","triggerScenarios":"Enqueuing many websocket messages (or one very large message) via enqueue()/send()/send_raw() such that the cumulative UTF-8 byte size of queued messages exceeds the configured max_bytes before the queue is drained.","commonSituations":"High-frequency producers outpacing a slow or stalled websocket connection; a producer thread enqueueing while the network is blocked; very large payloads exceeding the entire queue budget in one message.","solutions":["Catch WebSocketQueueFullError and apply backpressure: slow the producer, drop the message, or retry","Increase the queue byte limit when constructing the send queue if the workload legitimately needs more buffering","Drain/flush the queue before enqueueing bursts, and check queued size before adding large messages"],"exampleFix":"# before\nqueue.send(json.dumps(big_payload))  # may raise WebSocketQueueFullError\n\n# after\ntry:\n    queue.send(json.dumps(big_payload))\nexcept WebSocketQueueFullError:\n    time.sleep(0.1)  # backpressure, then retry","handlingStrategy":"try-catch","validationCode":"# before enqueueing a large message, check headroom\nmsg = json.dumps(payload)\nif queue._bytes + len(msg.encode('utf-8')) > queue._max_bytes:\n    queue.flush_sync(ws.send)  # drain first","typeGuard":null,"tryCatchPattern":"from openai._send_queue import WebSocketQueueFullError\ntry:\n    queue.send(message)\nexcept WebSocketQueueFullError:\n    await asyncio.sleep(0.1)\n    queue.send(message)  # or drop/backpressure","preventionTips":["Bound producer rates relative to socket throughput","Drain the queue before enqueueing bursts","Size max_bytes to your worst-case buffered payload volume"],"tags":["websocket","queue","backpressure","send"],"backgroundTag":"websocket-send-queue-full","analyzedSha":"9917c6e28e66e90e1227b3d223c06a8c5441515a","analyzedAt":"2026-08-28T11:46:34.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}