Locust non-zero exit with --exit-code-on-error in CI

By Daniel Zoghalchali·Latchkey

By default Locust exits 0 even with failures. --exit-code-on-error 1 makes it exit non-zero when any request failed, turning the run into a CI gate. A failing job then means the load test recorded real request failures.

What this error means

The Locust step fails with a non-zero exit even though it ran to completion, because failures occurred and --exit-code-on-error is set.

Shutting down (exit code 1), bye.
--check-fail-ratio / --exit-code-on-error triggered: 4.20% of requests failed

Common causes

Requests failed and the gate is enabled

With --exit-code-on-error 1, any recorded failure produces a non-zero exit, which is the intended gate.

Fail-ratio or check thresholds were exceeded

Using --check-fail-ratio or --check-avg-response-time, exceeding the limit sets the error exit code deliberately.

How to fix it

Treat the non-zero exit as a real signal

1. Read the failures column to see which endpoint failed.
2. Fix the underlying failure (auth, capacity, wrong path).
3. Keep the gate so regressions cannot pass silently.

locust --headless -u 100 -r 10 --run-time 1m \
  --host http://localhost:8080 --exit-code-on-error 1

Gate on a tolerable failure ratio

Allow a small failure ratio instead of any-failure if a few transient errors are acceptable.

locust --headless ... --check-fail-ratio 0.01 --check-avg-response-time 500

How to prevent it

• Choose exit-code-on-error or check-fail-ratio to match your gate policy.
• Fix the underlying request failures rather than removing the gate.
• Keep the gate so performance regressions fail the pipeline.

Frequently asked questions

Related guides

References

• GitHub Actions documentation