locustio/locust · error · ValueError

wait is True but the amount of users to add is greater than

Error message

wait is True but the amount of users to add is greater than the spawn rate

What it means

ValueError raised by Runner._start when wait=True but the requested increase in user count exceeds what the current spawn_rate allows. This guard exists because with wait=True the caller asserts the spawn can complete within one spawn-rate tick; locust refuses instead of silently waiting indefinitely.

Source

Thrown at locust/runners.py:489

        :param spawn_rate: Number of users to spawn per second
        :param wait: If True calls to this method will block until all users are spawned.
                     If False (the default), a greenlet that spawns the users will be
                     started and the call to this method will return immediately.
        :param user_classes: The user classes to be dispatched, None indicates to use the classes the dispatcher was
                             invoked with.
        """
        self.target_user_count = user_count

        if self.state != STATE_RUNNING and self.state != STATE_SPAWNING:
            self.stats.clear_all()
            self.exceptions = {}
            self.cpu_warning_emitted = False
            self.worker_cpu_warning_emitted = False
            self.environment._filter_tasks_by_tags()
            self.environment.events.test_start.fire(environment=self.environment)

        if wait and user_count - self.user_count > spawn_rate:
            raise ValueError("wait is True but the amount of users to add is greater than the spawn rate")

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

        if self.state != STATE_INIT and self.state != STATE_STOPPED:
            self.update_state(STATE_SPAWNING)

        if self._users_dispatcher is None:
            self._users_dispatcher = self.environment.dispatcher_class(
                worker_nodes=[self._local_worker_node], user_classes=self.user_classes
            )

        logger.info("Ramping to %d users at a rate of %.2f per second" % (user_count, spawn_rate))

        self._users_dispatcher.new_dispatch(user_count, spawn_rate, user_classes)

        try:

View on GitHub (pinned to f391a716e1)

Solutions

Pass wait=False if you just want the target user count reached as fast as the spawn rate allows
Raise spawn_rate so it is >= the user delta: `runner.start(target, spawn_rate=delta, wait=True)`
Increase spawn_rate and keep wait=True only for small, bounded user increases
Compute the delta first and validate it against spawn_rate before calling start

Example fix

// before
runner.start(100, wait=True)  # ValueError: delta 80 > spawn_rate 1
// after
runner.start(100, spawn_rate=80, wait=True)  # or use wait=False

Defensive patterns

Strategy: validation

Validate before calling

delta = target_users - runner.user_count
if wait and delta > spawn_rate:
    raise ValueError(f'spawn_rate {spawn_rate} too low for delta {delta} with wait=True')

Try / catch

try:
    runner.start(target_users, spawn_rate=spawn_rate, wait=True)
except ValueError:
    runner.start(target_users, spawn_rate=spawn_rate, wait=False)

Prevention

Set spawn_rate >= expected user delta when using wait=True
Default to wait=False unless you specifically need the one-tick guarantee
Validate target user counts against spawn_rate before calling start
Remember the default spawn_rate is small (1/s) — scale it for large jumps

When it happens

Trigger: Calling environment.runner.start(user_count, wait=True) (or spawning via Environment.start with wait) where user_count - current_user_count > spawn_rate — e.g. start(100, wait=True) when 20 users are running and spawn_rate defaults to 1.

Common situations: Default spawn_rate=1 while requesting many more users; UI/API-driven scaling calls passing wait=True with a large delta; scripts copied from examples without adjusting spawn_rate.

Related errors

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