locust worker connection refused to master: how to fix

TL;DR

Connection refused means the worker's packets never reached a listening master: wrong master host, master bound to the wrong interface, or a firewall in between. Verify the master is listening on a reachable address, point the worker at the right host and port, and open the firewall. The workers then join the swarm.

Error

locust worker connection refused to master: how to fix

Locust worker fails at startup: connection refused to the master host and port.

Steps

1. Check the master is actually listening: look for its startup log line with the bind address and port. Expected output: you see the master bound to an address and its two ports.
2. Verify reachability from the worker machine: a simple TCP check to the master host and port. Expected output: the port is open from where the worker runs.
3. Fix the bind: the master must listen on the all-interfaces address (or the specific interface workers use), not just the loopback. Expected output: the master's log shows a non-loopback bind.
4. Point workers correctly: --master-host with the master's reachable hostname, matching ports. Expected output: worker logs show connection attempts to the right address.
5. Open firewalls between workers and master for both ports. Expected output: workers connect and appear in the master's worker count.

When to use

• Locust workers fail with connection refused.
• Setting up distributed Locust for the first time.
• Workers and master run on different machines or containers.

When not to use

• Workers connect then drop (that is a version mismatch or network instability).
• Running standalone (no master involved).
• The master itself crashes (fix the master first).

Variant phrasings

Workers connect then drop

Version skew between master and workers, or heartbeats blocked; align versions first.

Connection refused in Docker Compose

Use the Compose service name as --master-host; the container's own hostname is not reachable from peers.

TLS in front of master

The worker protocol is plain TCP; a TLS-terminating proxy in front breaks it unless terminated correctly.

Why it happens

Locust's distributed mode is two plain TCP connections (command and heartbeat) from worker to master. Anything that breaks plain TCP reachability (wrong bind, wrong host, firewall) shows up as connection refused before any Locust logic runs.

Edge cases

• Both ports must be open; opening only one gives a worker that connects but never receives work.
• NAT between workers and master can break the heartbeat's return path; prefer flat networking for the Locust tier.
• A stale master process from a killed run can hold the ports; kill orphans before starting a new master.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_iqweBynaOPoLEdGIZh-pdg