locustio/locust · error · RPCReceiveError

ZMQ interrupted or corrupted message

Error message

ZMQ interrupted or corrupted message

What it means

RPCReceiveError raised in recv_from_client when the address frame (the first part of the multipart message on the master's ROUTER socket) cannot be decoded as UTF-8. This indicates the multipart frame was corrupted or is not from a locust node, so the message cannot be attributed to a client.

Source

Thrown at locust/rpc/zmqrpc.py:53

        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

    def close(self, linger=None):
        self.socket.close(linger=linger)

    def ipv4_only(self, host, port) -> bool:
        try:
            if host == "*":
                return False
            if str(csocket.getaddrinfo(host, port, proto=csocket.IPPROTO_TCP)).find("Family.AF_INET6") == -1:
                return True
        except gaierror as e:

View on GitHub (pinned to f391a716e1)

Solutions

1. Verify only locust workers connect to the master port; firewall it from other traffic
2. Ensure master and worker locust versions match
3. Restart the master to reset the corrupted ZMQ stream
4. Check network path for corruption (middleboxes, MTU problems)

try:
    addr, msg = server.recv_from_client()
except RPCReceiveError:
    logger.error('received corrupt frame from unknown client; dropping')
    continue

When it happens

Trigger: Master calling recv_from_client() and hitting UnicodeDecodeError on data[0] — a garbled first frame from a corrupted stream or a non-locust client connecting to the ROUTER port.

Common situations: Something other than a locust worker connected to the master's ZMQ TCP port; truncated/corrupted TCP stream; binary garbage sent to the port by a scanner or misconfigured client.

Related errors

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

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