locustio/locust · critical · RPCError

Socket bind failure: {e}

Error message

Socket bind failure: {e}

What it means

RPCError raised by the ZMQ Server (master) when socket.bind() to the requested tcp host:port fails. The ZMQ error text (e.g. 'Address already in use') is embedded in the message. Locust wraps it so the master fails fast with a clear message instead of a raw ZMQError.

Source

Thrown at locust/rpc/zmqrpc.py:87

            if str(csocket.getaddrinfo(host, port, proto=csocket.IPPROTO_TCP)).find("Family.AF_INET6") == -1:
                return True
        except gaierror as e:
            print(f"Error resolving address: {e}")
            return False
        return False


class Server(BaseSocket):
    def __init__(self, host, port):
        BaseSocket.__init__(self, zmq.ROUTER, self.ipv4_only(host, port))
        if port == 0:
            self.port = self.socket.bind_to_random_port(f"tcp://{host}")
        else:
            try:
                self.socket.bind("tcp://%s:%i" % (host, port))
                self.port = port
            except zmqerr.ZMQError as e:
                raise RPCError(f"Socket bind failure: {e}")


class Client(BaseSocket):
    def __init__(self, host, port, identity):
        BaseSocket.__init__(self, zmq.DEALER, self.ipv4_only(host, port))
        self.socket.setsockopt(zmq.IDENTITY, identity.encode())
        self.socket.connect("tcp://%s:%i" % (host, port))

View on GitHub (pinned to f391a716e1)

Solutions

1. Find and stop the process holding the port: `lsof -i :5557` or `ss -tlnp | grep 5557`, then kill the stale master
2. Start the master with a different port: `locust --master --master-bind-port 5558`
3. If binding to a specific host, use 0.0.0.0, '*', or an IP actually assigned to the machine
4. In Docker/Kubernetes, verify the port is not claimed by another container/pod

Example fix

// before
locust --master  # Error: Socket bind failure: Address already in use (port 5557)
// after
lsof -i :5557    # kill stale master PID
locust --master --master-bind-port 5558

import socket
s = socket.socket()
try:
    s.bind((bind_host, bind_port))
    print('port free')
except OSError:
    print(f'port {bind_port} already in use - pick another --master-bind-port')
finally:
    s.close()

try:
    server = rpc.Server(master_bind_host, master_bind_port)
except RPCError as e:
    logger.error(f'cannot bind ZMQ port: {e} - stop the stale process or use another port')
    sys.exit(1)

When it happens

Trigger: Starting a master with --master-bind-port (or default 8089-independent ZMQ port 5557) already taken by another process, or binding to a host/IP not local to the machine.

Common situations: A previous locust master still running and holding the port; another service on 5557; stale container/process; specifying --master-bind-host as an address not assigned to the machine.

Related errors

• ZMQ sent failure
• ZMQ interrupted message
• ZMQ network broken
• ZMQ interrupted or corrupted message
• 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/94405ebb1857b4c5. Report an issue: GitHub.