openai/openai-python · error · WebSocketQueueFullError

send queue is full, message discarded

Error message

send queue is full, message discarded

What it means

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.

Source

Thrown at src/openai/_send_queue.py:36

    """

    def __init__(self, max_bytes: int = 1_048_576) -> None:
        self._queue: list[tuple[str, int]] = []  # (data, byte_length)
        self._bytes: int = 0
        self._max_bytes = max_bytes
        self._lock = threading.Lock()
        self._flush_done: threading.Event | None = None

    def enqueue(self, data: str) -> None:
        """Append *data* to the queue.

        Raises :class:`WebSocketQueueFullError` if the message would
        exceed the byte-size limit.
        """
        byte_length = len(data.encode("utf-8"))
        with self._lock:
            if self._bytes + byte_length > self._max_bytes:
                raise WebSocketQueueFullError("send queue is full, message discarded")
            self._queue.append((data, byte_length))
            self._bytes += byte_length

    def flush_sync(self, send: typing.Callable[[str], object]) -> None:
        """Send every queued message via *send*.

        If *send* raises, the failing message and all subsequent messages
        are re-queued and the error is re-raised.
        """
        while isinstance(pending := self._begin_flush(), threading.Event):
            pending.wait()

        try:
            while pending:
                data, byte_length = pending[0]
                send(data)
                with self._lock:
                    pending.popleft()

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Catch WebSocketQueueFullError and apply backpressure: slow the producer, drop the message, or retry
2. Increase the queue byte limit when constructing the send queue if the workload legitimately needs more buffering
3. Drain/flush the queue before enqueueing bursts, and check queued size before adding large messages

Example fix

# before
queue.send(json.dumps(big_payload))  # may raise WebSocketQueueFullError

# after
try:
    queue.send(json.dumps(big_payload))
except WebSocketQueueFullError:
    time.sleep(0.1)  # backpressure, then retry

# before enqueueing a large message, check headroom
msg = json.dumps(payload)
if queue._bytes + len(msg.encode('utf-8')) > queue._max_bytes:
    queue.flush_sync(ws.send)  # drain first

from openai._send_queue import WebSocketQueueFullError
try:
    queue.send(message)
except WebSocketQueueFullError:
    await asyncio.sleep(0.1)
    queue.send(message)  # or drop/backpressure

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• The `data_residency` and `websocket_base_url` arguments are
• You need to install `openai[realtime]` to use this method
• WebSocket connection closed with unsent messages
• WebSocket error: {event}
• You need to install `openai[realtime]` to use this method

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/147db690b9dc485f. Report an issue: GitHub.