locustio/locust · error · NotImplementedError

use start_worker

Error message

use start_worker

What it means

WorkerRunner does not support the generic UserRunner.start() API used by the master/local runners. Calling start() on a worker-mode runner raises this explicit NotImplementedError to point the developer at the worker-specific start_worker() method, which takes a dict of user class names to counts instead of a user count and spawn rate.

Source

Thrown at locust/runners.py:1291

            self.client.send(Message("exception", {"msg": str(exception), "traceback": formatted_tb}, self.client_id))

        self.environment.events.user_error.add_listener(on_user_error)

    def spawning_complete(self, user_count):
        assert user_count == sum(self.user_classes_count.values())
        self.client.send(
            Message(
                "spawning_complete",
                {"user_classes_count": self.user_classes_count, "user_count": self.user_count},
                self.client_id,
            )
        )
        self.worker_state = STATE_RUNNING

    def start(
        self, user_count: int, spawn_rate: float, wait: bool = False, user_classes: list[type[User]] | None = None
    ) -> None:
        raise NotImplementedError("use start_worker")

    def start_worker(self, user_classes_count: dict[str, int], **kwargs) -> None:
        """
        Start running a load test as a worker

        :param user_classes_count: Users to run
        """
        self.target_user_classes_count = user_classes_count
        self.target_user_count = sum(user_classes_count.values())

        for user_class in self.user_classes:
            if self.environment.host:
                user_class.host = self.environment.host

        user_classes_spawn_count: dict[str, int] = {}
        user_classes_stop_count: dict[str, int] = {}

        for user_class_name, user_class_count in user_classes_count.items():

View on GitHub (pinned to f391a716e1)

Solutions

1. Call runner.start_worker({'MyUserClass': count}) instead of runner.start(...)
2. Check the runner type (isinstance(runner, WorkerRunner)) before invoking start()
3. If driving workers programmatically, let the master distribute user counts rather than starting tasks directly on the worker

Example fix

// before
runner.start(100, 10)
// after
if isinstance(runner, WorkerRunner):
    runner.start_worker({"MyHttpUser": 100})
else:
    runner.start(100, 10)

if isinstance(runner, WorkerRunner):
    raise RuntimeError("Use start_worker() on worker runners")

from locust.runners import WorkerRunner
def is_worker(runner):
    return isinstance(runner, WorkerRunner)

When it happens

Trigger: Calling runner.start(user_count, spawn_rate) on a WorkerRunner instance, e.g. after launching locust with --worker and programmatically invoking the runner API intended for standalone/master mode.

Common situations: Scripts that reuse the same start() call for both local and worker mode; custom orchestration code that connects a worker node and tries to drive it like a master; refactoring shared runner code without checking runner type.

Related errors

• User.run() is a method used internally by Locust, and you mu
• In order to use a with-block for requests, you must also pas
• Tried to set status on a request that has not yet been made.
• If you want to change the state of the request using .succes
• You must specify the base host. Either in the host attribute

AI-assisted analysis of locustio/locust@f391a716e1 (2026-08-29). Data as JSON: /api/errors/7cc0184c5d416ee6. Report an issue: GitHub.