{"record":{"id":"4d6cb408e0e89073","repo":"locustio/locust","slug":"wait-is-true-but-the-amount-of-users-to-add-is-gre","errorCode":null,"errorMessage":"wait is True but the amount of users to add is greater than the spawn rate","messagePattern":"wait is True but the amount of users to add is greater than the spawn rate","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"locust/runners.py","lineNumber":489,"sourceCode":"        :param spawn_rate: Number of users to spawn per second\n        :param wait: If True calls to this method will block until all users are spawned.\n                     If False (the default), a greenlet that spawns the users will be\n                     started and the call to this method will return immediately.\n        :param user_classes: The user classes to be dispatched, None indicates to use the classes the dispatcher was\n                             invoked with.\n        \"\"\"\n        self.target_user_count = user_count\n\n        if self.state != STATE_RUNNING and self.state != STATE_SPAWNING:\n            self.stats.clear_all()\n            self.exceptions = {}\n            self.cpu_warning_emitted = False\n            self.worker_cpu_warning_emitted = False\n            self.environment._filter_tasks_by_tags()\n            self.environment.events.test_start.fire(environment=self.environment)\n\n        if wait and user_count - self.user_count > spawn_rate:\n            raise ValueError(\"wait is True but the amount of users to add is greater than the spawn rate\")\n\n        for user_class in self.user_classes:\n            if self.environment.host:\n                user_class.host = self.environment.host\n\n        if self.state != STATE_INIT and self.state != STATE_STOPPED:\n            self.update_state(STATE_SPAWNING)\n\n        if self._users_dispatcher is None:\n            self._users_dispatcher = self.environment.dispatcher_class(\n                worker_nodes=[self._local_worker_node], user_classes=self.user_classes\n            )\n\n        logger.info(\"Ramping to %d users at a rate of %.2f per second\" % (user_count, spawn_rate))\n\n        self._users_dispatcher.new_dispatch(user_count, spawn_rate, user_classes)\n\n        try:","sourceCodeStart":471,"sourceCodeEnd":507,"githubUrl":"https://github.com/locustio/locust/blob/f391a716e12c2c712e80b5835e877b7933397453/locust/runners.py#L471-L507","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nrunner.start(100, wait=True)  # ValueError: delta 80 > spawn_rate 1\n// after\nrunner.start(100, spawn_rate=80, wait=True)  # or use wait=False","handlingStrategy":"validation","validationCode":"delta = target_users - runner.user_count\nif wait and delta > spawn_rate:\n    raise ValueError(f'spawn_rate {spawn_rate} too low for delta {delta} with wait=True')","typeGuard":null,"tryCatchPattern":"try:\n    runner.start(target_users, spawn_rate=spawn_rate, wait=True)\nexcept ValueError:\n    runner.start(target_users, spawn_rate=spawn_rate, wait=False)","preventionTips":["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"],"tags":["valueerror","spawn-rate","user-count","runner"],"backgroundTag":"spawn-rate-exceeded","analyzedSha":"f391a716e12c2c712e80b5835e877b7933397453","analyzedAt":"2026-08-29T00:36:13.872Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}