Locust's argument parser rejected a flag it does not know. In CI this is usually a renamed option (like the old --no-web replaced by --headless) or a custom argument not registered via the parser hook.
What this error means
Locust exits immediately with "locust: error: unrecognized arguments: --flag value" and a non-zero code, before any load is generated.
Before debugging an assertion, establish whether the test fails consistently. A test that passes alone and fails in the suite is sharing state; one that fails intermittently is racing something. Neither is fixed in the assertion.
Terminal
# in isolation
<runner> path/to/one.test
# order dependence
<runner> --shuffle # or the runner equivalent
# raciness
for i in $(seq 1 20); do <runner> path/to/one.test || break; done
Common causes
A renamed or removed flag
Older flags such as --no-web and --clients were replaced by --headless and --users; passing the old names is rejected.
A custom argument not registered
A --my-option used by the locustfile must be declared with @events.init_command_line_parser or Locust will not recognize it.
How to fix it
Use the current flag names
Run locust --help to see the supported flags for your version.
Replace --no-web with --headless and --clients with --users.
Pass --run-time and --spawn-rate for a bounded headless run.
Declare custom arguments in the locustfile so the parser accepts them.
locustfile.py
from locust import events
@events.init_command_line_parser.add_listener
def _(parser):
parser.add_argument("--my-option", type=str, default="")
How to prevent it
Check locust --help after upgrades for renamed flags.
Register every custom option via the parser hook.
Prefer --headless -u -r --run-time for CI runs.
Frequently asked questions
What causes Locust "error: unrecognized arguments" in CI?
There are 2 common causes: a renamed or removed flag and a custom argument not registered. Older flags such as --no-web and --clients were replaced by --headless and --users; passing the old names is rejected.
How do I fix Locust "error: unrecognized arguments" in CI?
There are 2 fixes depending on which cause you have: use the current flag names and register custom command-line options. Work through them in order, since the first is the most common.
What does Locust "error: unrecognized arguments" in CI actually mean?
Locust exits immediately with "locust: error: unrecognized arguments: --flag value" and a non-zero code, before any load is generated.
How do I stop Locust "error: unrecognized arguments" in CI happening again?
Check locust --help after upgrades for renamed flags. The prevention section lists 3 changes that keep it from recurring.
