What causes "write() called with empty data {data!r}" in pika/pika?

Guard the write with `if data:` before calling the internal buffer path

pika/pika · warning · ValueError

write() called with empty data {data!r}

Error message

write() called with empty data {data!r}

What it means

_AsyncTransportBase._buffer_tx_data refuses to buffer an empty bytes payload, because queueing an empty write is wasteful and can spin event loops. This is an internal transport invariant; the public write path should never produce empty data. Hitting it usually means a framing bug or a caller sending b''.

Source

Thrown at pika/adapters/utils/io_services_utils.py:787

    @override
    def get_write_buffer_size(self) -> int:
        """
        :returns: Current size of output data buffered by the transport
        """
        return self._tx_buffered_byte_count

    def _buffer_tx_data(self, data: bytes) -> None:
        """
        Buffer the given data until it can be sent asynchronously.

        :param data:
        :raises ValueError: if called with empty data
        """
        if not data:
            _LOGGER.error('write() called with empty data: state=%s; %s',
                          self._state, self._sock)
            raise ValueError(f'write() called with empty data {data!r}')

        if self._state != self._STATE_ACTIVE:
            _LOGGER.debug(
                'Ignoring write() called during inactive state: '
                'state=%s; %s', self._state, self._sock)
            return

        self._tx_buffers.append(data)
        self._tx_buffered_byte_count += len(data)

    def _consume(self) -> None:
        """
        Utility method for use by subclasses to ingest data from socket and dispatch it to
        protocol's `data_received()` method socket-specific "try again" exception, per-event data
        consumption limit is reached, transport becomes inactive, or a fatal failure.

        Consumes up to `self._MAX_CONSUME_BYTES` to prevent event starvation or until state becomes
        inactive (e.g., `protocol.data_received()` callback aborts the transport)

View on GitHub (pinned to 34a407b24f)

Solutions

Guard the write with `if data:` before calling the internal buffer path
Trace the upstream caller producing zero-length payloads
If using only pika's public API, file a bug - this signals an internal framing error

Example fix

# before
transport._buffer_tx_data(b'')  # ValueError

# after
if data:
    transport._buffer_tx_data(data)

Defensive patterns

Strategy: validation

Validate before calling

def safe_buffer(transport, data):
    if data:  # skip empty payloads
        transport._buffer_tx_data(data)

safe_buffer(transport, payload)

Try / catch

try:
    transport._buffer_tx_data(data)
except ValueError as e:
    if 'empty data' in str(e):
        pass  # ignore empty write
    else:
        raise

Prevention

Guard internal writes with `if data:` before buffering
Avoid calling private transport buffer methods directly; use the public write path
If this surfaces from pika internals while using only public APIs, file a bug

When it happens

Trigger: A transport/protocol caller invoking the internal write path with b'' or another falsy bytes value; a framing bug producing zero-length frames.

Common situations: Custom transport/protocol that flushes buffers even when empty; a bug in pika's own framing (rare). End users of the public API normally never hit this directly.

Related errors

AI-assisted analysis of pika/pika@34a407b24f (2026-08-07). Data as JSON: /api/errors/7045ca934e2f29de. Report an issue: GitHub.