A Gatling run exits 1 on a build runner. Does that prove the command line was wrong?

`1` is the most misleading value Gatling can hand a build runner, because two completely different situations produce it and only one of them is the one the name suggests. ## What `1` is declared to mean Gatling's `StatusCode` names `1` `InvalidArguments`. The argument parser returns it when it cannot make sense of the command line, and the main entry point exits with that value. That much matches the name. ## The other way to reach `1` Gatling's run wrapper catches failures in two arms: - a lifecycle exception — configuration loading, instantiating the simulation, a `before` or `after` hook, building the scenarios, or the injection itself failing — is logged and then its **cause is rethrown**; - any other `Throwable` is logged as `Run crashed` and **rethrown** as well. Neither arm maps to a `StatusCode`. The rethrown exception propagates out of `main`, so the line that would have called the exit function with a status code is never reached. The JVM ends on an uncaught exception in the main thread, and that terminates the process with **`1`**. A build runner cannot tell the two apart from the integer. It sees `1` for a rejected command line and `1` for a simulation that blew up halfway through injection. The difference is only in the run's own output: a rethrown crash leaves a `Run crashed` line and a stack trace there; a rejected command line leaves a parser message and no run at all. Look for them on the console, not in the results directory — both are SLF4J calls and Gatling's shipped logback configuration declares a single console appender and no file appender, so nothing routes them to a file. The only `.log` written under a results directory is `simulation.log`, and that is a binary record stream: it carries the run's statistics and the messages of its failed requests, never a log line such as `Run crashed`. On the mistyped-option route there is no results directory to search in the first place, because the run dies before one is created. ## And a third: a fatal error inside an action Separately from the status-code scheme, a handful of sites call the exit function with `1` directly. The most important is Gatling's action base: when an action throws something fatal — as opposed to a normal failure, which just marks the virtual user's session failed and moves on — Gatling logs `Gatling crashed` and terminates the JVM on the spot. No reports, no assertions, no verdict. So three distinct routes end at the same integer: - **the parser** returning the invalid-arguments code, the only one the name describes; - **a rethrown crash**, where the status-code path was never reached at all; - **a direct termination** from a fatal error inside an action, outside the status-code scheme entirely. ## The trap that ties them together Gatling's command-line parser deliberately **turns off erroring on unknown arguments**. An option the parser does not recognise is not rejected; parsing succeeds and the option is dropped. So: 1. You mistype `--simulation` as `--simulaton`. 2. The parser does not recognise it, does not error, and does not set the simulation class. 3. Gatling later goes to resolve which simulation to run, finds nothing, and throws. 4. That throw goes through the rethrow path, and the process exits `1`. The outcome — exit `1` after a typo in an argument — looks exactly like `InvalidArguments`, and it never touched that code. This is worth internalising, because the fix ("read the run's output, not the integer") is not obvious from the symptom. ## A related pair in the DSL Two stop constructs differ precisely in the signal they leave behind. `stopLoadGenerator` ends the run gracefully — the run finishes, assertions are evaluated, and the exit code is the usual `0` or `2`. `crashLoadGenerator`, added when the older injector-named options were renamed in **3.12**, is the same stop except that it is treated as a crash: the run's completion fails, the wrapper rethrows, and the process ends non-zero through the crash path rather than returning a status code. If you want a run to end early *and* be unmistakably a failure, that difference is the one that matters. ## What to do with it | observation | what it actually tells you | |---|---| | exit `0` | nothing failed that was asserted — possibly nothing was asserted | | exit `1` | Gatling produced **no verdict**: bad arguments, or the run died | | exit `2` | a verdict was produced and at least one assertion did not hold | | anything else | no `StatusCode` was returned: the process was killed, the JVM died, or simulation code exited it | The practical rule: **treat `1` as "no result", not as "failed"**. A run that never produced a verdict should be surfaced differently from a run that produced a bad one, because the responses are different — one is investigated, the other is retried or fixed in the job definition. One last wrinkle for anyone running simulations through sbt's test framework rather than the JVM launcher: that path catches the exception itself and reports it using the assertions-failed code. The same crash therefore surfaces as `1` under one launcher and as a failed test under the other, which is worth knowing before you conclude that two runners disagree about what happened.