locustio/locust · error · RPCReceiveError

ZMQ interrupted message

Error message

ZMQ interrupted message

What it means

RPCReceiveError raised when Message.unserialize fails with a msgpack ExtraData error while receiving on a ZMQ socket. It means the received bytes were interrupted or contain trailing data that msgpack could not decode as a single Message. The library raises this instead of letting raw msgpack errors propagate through the runner.

Source

Thrown at locust/rpc/zmqrpc.py:43

    def send(self, msg):
        try:
            self.socket.send(msg.serialize(), zmq.NOBLOCK)
        except zmqerr.ZMQError as e:
            raise RPCSendError("ZMQ sent failure") from e

    @retry()
    def send_to_client(self, msg):
        try:
            self.socket.send_multipart([msg.node_id.encode(), msg.serialize()])
        except zmqerr.ZMQError as e:
            raise RPCSendError("ZMQ sent failure") from e

    def recv(self):
        try:
            data = self.socket.recv()
            msg = Message.unserialize(data)
        except msgerr.ExtraData as e:
            raise RPCReceiveError("ZMQ interrupted message") from e
        except zmqerr.ZMQError as e:
            raise RPCError("ZMQ network broken") from e
        return msg

    def recv_from_client(self):
        try:
            data = self.socket.recv_multipart()
            addr = data[0].decode()
        except UnicodeDecodeError as e:
            raise RPCReceiveError("ZMQ interrupted or corrupted message") from e
        except zmqerr.ZMQError as e:
            raise RPCError("ZMQ network broken") from e
        try:
            msg = Message.unserialize(data[1])
        except (UnicodeDecodeError, msgerr.ExtraData) as e:
            raise RPCReceiveError("ZMQ interrupted or corrupted message", addr=addr) from e
        return addr, msg

View on GitHub (pinned to f391a716e1)

Solutions

1. Ensure all master/worker nodes run the same locust version (wire protocol compatibility)
2. Restart the affected runner so the ZMQ connection and stream are re-established
3. Check for other processes bound to the same port sending invalid data
4. Investigate network instability (MTU issues, flaky links) between the nodes

try:
    msg = client.recv()
except RPCReceiveError as e:
    logger.error(f'corrupted message received: {e}')
    # reconnect/restart the runner

When it happens

Trigger: A recv() on a BaseSocket where the incoming payload is a truncated or corrupted msgpack stream — e.g. a partial message delivered after a broken connection, or a peer sending malformed bytes.

Common situations: Network interruption mid-message between master and worker; a non-locust process connected to the same ZMQ TCP port and sent garbage; mismatched locust/protocol versions between nodes.

Related errors

• ZMQ interrupted or corrupted message
• You need to install pymongo or at least bson to be able to s
• ZMQ sent failure
• ZMQ network broken
• Socket bind failure: {e}

AI-assisted analysis of locustio/locust@f391a716e1 (2026-08-29). Data as JSON: /api/errors/8e883e97f3c3af23. Report an issue: GitHub.