locust error: worker failed to connect to master - how to fix distributed load testing

locust error: worker failed to connect to master - how to fix distributed load testing

TL;DR

Workers connect to the master over TCP (default port 5557/5558). When they cannot, it is almost always the network path, a port mismatch, or a locust version mismatch between master and workers. Align the versions, open the ports, and point workers at the master's reachable address.

locust error: worker failed to connect to master

Steps

1. Confirm versions match: locust --version on master and every worker. Mixed versions fail the handshake. Expected: All nodes report the same version.

2. Check the worker's target address: it must be the master's reachable IP or hostname when running on separate hosts; the loopback address only works when the worker shares the master's host. Expected: The worker points at an address that routes to the master.

3. Verify the ports are open between the nodes: master listens on 5557 (and 5558 for the web UI if used). Test with telnet or nc from the worker host. Expected: The connection succeeds at the TCP level.

4. Check firewalls and security groups on both sides, including container network policies if the master runs in a pod. Expected: No rule drops the worker-to-master traffic.

5. Start the master first with --master, then workers with --worker --master-host=[addr]; watch the master log for 'Client connected' lines. Expected: Workers register and the run starts.

When to use

• locust workers fail to connect to the master
• setting up distributed locust for the first time
• workers worked locally but fail across hosts

When not to use

• a single locust process fails (that is not a distributed problem)
• workers connect but no traffic flows (check the task sets)
• the master UI is unreachable (that is port 8089, a different listener)

Tool compatibility

• Locust 2.x
• master/worker over TCP 5557

Variant phrasings

• "locust worker failed to connect to master"
• "locust distributed worker cannot connect"
• "locust master host connection refused"

Why it happens

Locust's distributed mode is a simple TCP mesh: workers dial the master on fixed ports and exchange heartbeats. There is no discovery and no retry with backoff worth mentioning, so any network or version skew shows up immediately as a connection failure rather than degraded performance.

Edge cases

• DNS inside containers may resolve the master name differently; prefer IPs for worker --master-host
• running workers with --processes spawns multiple worker processes per host; each needs the ports reachable
• a stale master from a previous run holding the ports produces confusing 'connected but idle' behavior; kill it first

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_bqvGocktwO-pyM6U8JR3nw