{"record":{"id":"94405ebb1857b4c5","repo":"locustio/locust","slug":"socket-bind-failure-e","errorCode":null,"errorMessage":"Socket bind failure: {e}","messagePattern":"Socket bind failure: (.+?)","errorType":"exception","errorClass":"RPCError","httpStatus":null,"severity":"critical","filePath":"locust/rpc/zmqrpc.py","lineNumber":87,"sourceCode":"            if str(csocket.getaddrinfo(host, port, proto=csocket.IPPROTO_TCP)).find(\"Family.AF_INET6\") == -1:\n                return True\n        except gaierror as e:\n            print(f\"Error resolving address: {e}\")\n            return False\n        return False\n\n\nclass Server(BaseSocket):\n    def __init__(self, host, port):\n        BaseSocket.__init__(self, zmq.ROUTER, self.ipv4_only(host, port))\n        if port == 0:\n            self.port = self.socket.bind_to_random_port(f\"tcp://{host}\")\n        else:\n            try:\n                self.socket.bind(\"tcp://%s:%i\" % (host, port))\n                self.port = port\n            except zmqerr.ZMQError as e:\n                raise RPCError(f\"Socket bind failure: {e}\")\n\n\nclass Client(BaseSocket):\n    def __init__(self, host, port, identity):\n        BaseSocket.__init__(self, zmq.DEALER, self.ipv4_only(host, port))\n        self.socket.setsockopt(zmq.IDENTITY, identity.encode())\n        self.socket.connect(\"tcp://%s:%i\" % (host, port))\n","sourceCodeStart":69,"sourceCodeEnd":95,"githubUrl":"https://github.com/locustio/locust/blob/f391a716e12c2c712e80b5835e877b7933397453/locust/rpc/zmqrpc.py#L69-L95","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Find and stop the process holding the port: `lsof -i :5557` or `ss -tlnp | grep 5557`, then kill the stale master","Start the master with a different port: `locust --master --master-bind-port 5558`","If binding to a specific host, use 0.0.0.0, '*', or an IP actually assigned to the machine","In Docker/Kubernetes, verify the port is not claimed by another container/pod"],"exampleFix":"// before\nlocust --master  # Error: Socket bind failure: Address already in use (port 5557)\n// after\nlsof -i :5557    # kill stale master PID\nlocust --master --master-bind-port 5558","handlingStrategy":"validation","validationCode":"import socket\ns = socket.socket()\ntry:\n    s.bind((bind_host, bind_port))\n    print('port free')\nexcept OSError:\n    print(f'port {bind_port} already in use - pick another --master-bind-port')\nfinally:\n    s.close()","typeGuard":null,"tryCatchPattern":"try:\n    server = rpc.Server(master_bind_host, master_bind_port)\nexcept RPCError as e:\n    logger.error(f'cannot bind ZMQ port: {e} - stop the stale process or use another port')\n    sys.exit(1)","preventionTips":["Check `lsof -i :5557` (or your port) before starting a master","Use --master-bind-port 0 or bind_to_random_port in ephemeral/test environments","In orchestrators, reserve the ZMQ port explicitly to avoid double-assignment","Bind to 0.0.0.0 or '*' unless a specific local IP is required"],"tags":["zmq","port-in-use","bind","startup","distributed"],"backgroundTag":"address-already-in-use","analyzedSha":"f391a716e12c2c712e80b5835e877b7933397453","analyzedAt":"2026-08-29T00:36:13.872Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}