Locust "Failed to connect to master" (distributed) in CI

By Daniel Zoghalchali·Latchkey

In distributed mode, Locust workers connect to the master on port 5557. "Failed to connect to master" means the worker cannot reach that address: the master was not up yet, the host is wrong, or the port is not routable in CI.

What this error means

Worker logs repeat "Failed to connect to master. Retrying..." and never register, so the master reports 0 workers and generates no load.

[WARNING] Failed to connect to master. Retrying...
[ERROR] RPCError found when connecting to master: [Errno 111] Connection refused
[WARNING] Master seems to have gone missing, giving up after 60 tries

Common causes

The master is not up or not reachable

Workers started before the master bound port 5557, or the master host is not routable from the worker network in CI.

Wrong master host or blocked port

The --master-host is wrong, or the master bind port (5557) and web port are not exposed between containers.

How to fix it

Start the master first and point workers at it

1. Launch the master and wait until it is listening.
2. Start each worker with the correct --master-host and --master-port.
3. Ensure port 5557 is routable between master and workers.

# master
locust -f locustfile.py --master --headless -u 200 -r 20 --expect-workers 2 &
# worker
locust -f locustfile.py --worker --master-host 127.0.0.1 --master-port 5557

Wait for the master and use --expect-workers

Have the master wait for its workers so the run does not start with zero, and gate workers behind master readiness.

locust --master --headless --expect-workers 2 --expect-workers-max-wait 60 ...

How to prevent it

• Start the master before workers and wait for it to bind.
• Route the master port (5557) between master and workers in CI.
• Use --expect-workers so a run never starts with zero generators.

Frequently asked questions

Related guides

References

• GitHub Actions documentation