In JMeter's OS Process Sampler, what makes a failing command fail the sample?

The **OS Process Sampler** is the shell-out escape hatch: it runs a command on the machine the thread is running on, which in a load plan is the injector rather than the system under test. Seeding an order queue with a fixture script, calling a broker's admin CLI to purge it, or invoking a tool that speaks a protocol no sampler covers are its honest uses. ## The exit code is recorded, not judged Every sample stores the process's exit status as the response code — a literal `0`, `1`, `3` and so on. But the success flag is decided separately: - **Check Return Code unticked** — the sample is marked successful, whatever the command returned. - **Check Return Code ticked** — JMeter compares the exit status with **Expected Return Code**, defaulting to `0`, and fails the sample when they differ. The response message reads `Unexpected return code. Expected [0]. Actual [3].` That default is the whole reason a plan can shell out to a script that has been failing for weeks and still show a green run. If you shell out, tick the box. ## Why 500 is reserved JMeter uses `500` as its own error indicator on this sampler. Three internal conditions set it: 1. an `IOException` while launching or running the command; 2. the sampler thread being interrupted; 3. the **Timeout** expiring, after which JMeter attempts to kill the OS process. The component reference says so directly and warns you not to use `500` as an expected return code — a process that legitimately exits `500` would be indistinguishable from JMeter failing to run it at all. ## The Timeout **Timeout** is in milliseconds and defaults to `0`, which means no timeout. A command that hangs therefore hangs the thread for the rest of the run. On any unattended plan, set a real value; on expiry the process is killed and the sample fails with `500`. ## What comes back - **Standard output (stdout)** and **Standard error (stderr)** name files. If a field is left empty, that stream is captured and returned as the sample's response data instead, where assertions and extractors can see it. - **Standard input (stdin)** names a file to feed the process. - **Working directory** defaults to the folder named by the `user.dir` system property. - **Environment Parameters** are key/value pairs added to the child process's environment. - The sampler data records the working directory, the environment and the exact command line it assembled, which is the first thing to read when a command behaves differently than it does in your terminal. ## No shell, no quoting This is the part that bites on the way to CI. The sampler passes the command and its parameters straight to the operating system: > *"The sampler deliberately does not do any parsing or quote handling. The command and its parameters must be provided in the form expected by the executable."* There is no shell in between, so wildcard expansion, pipes, redirection and quoting rules simply do not exist. Built-ins are not executables either — the Windows `DIR` command lives inside the command interpreter, so `DIR C:\TEMP` has to be entered as **Command** `CMD`, then parameters `/C`, `DIR`, `C:\TEMP`. The same plan will not be portable between operating systems, which is worth knowing before a `.jmx` written on a laptop is handed to a Linux CI runner. ## Where it goes wrong - **Check Return Code** left unticked, so a broken fixture script never fails a run. - `500` chosen as an expected code, colliding with JMeter's own error indicator. - A whole command line typed into **Command** as one string, so the OS looks for an executable with spaces in its name. - **Timeout** left at `0` on a command that can hang. - Forgetting that the command runs on the injector, so the sample's elapsed time measures local work, not the system under test.