How to stop a JMeter CLI test gracefully

A long JMeter load run sometimes has to end before its planned loop count or duration, but killing the Java process can interrupt result writes and leave remote engines busy. The non-GUI controller opens a shutdown listener so a separate client can ask JMeter to stop through its own control path.

The graceful client is shutdown.sh or shutdown.cmd in the bin directory of the same JMeter installation. It sends a shutdown request to the controller's listener, which normally listens on port 4445 and reports the request in the controller terminal.

Use the graceful client before the abrupt stoptest.sh or stoptest.cmd client. Test plans with bounded loop counts, scheduler durations, or samplers that return promptly can finish the current work and tidy up; plans that loop forever or block inside a sampler may keep running until an abrupt stop is chosen.

Related: How to run a JMeter test from the command line
Related: How to run a distributed JMeter test

Steps to stop a JMeter CLI test gracefully:

  1. Find the terminal that started the non-GUI controller. 
    $ jmeter -n -t checkout-load.jmx -l checkout-load.jtl -j checkout-load.log
Creating summariser <summary>
Created the tree successfully using checkout-load.jmx
Starting standalone test @ 2026 Jun 29 22:05:13 GMT
Waiting for possible Shutdown/StopTestNow/HeapDump/ThreadDump message on port 4445

    The graceful client must run on the controller host that owns the shutdown listener. For distributed tests, start the controller with -X when remote server JVMs should exit after the test ends.

  2. Send the graceful shutdown request from a second terminal on the controller host. 
    $ ./apache-jmeter-5.6.3/bin/shutdown.sh
Sending Shutdown request to port 4445

    On Windows, run apache-jmeter-5.6.3\bin\shutdown.cmd from a command prompt. Use stoptest.sh or stoptest.cmd only when the graceful request does not end the run.

  3. Wait for the controller terminal to show the shutdown request and end of run. 
    Command: Shutdown received from /127.0.0.1
summary +      1 in 00:00:01 =    1.0/s Avg:  1012 Min:  1012 Max:  1012 Err:     0 (0.00%) Active: 0 Started: 1 Finished: 1
summary =     17 in 00:00:18 =    1.0/s Avg:  1036 Min:  1001 Max:  1533 Err:     0 (0.00%)
Tidying up ...    @ 2026 Jun 29 22:05:31 GMT
... end of run

    If the summary keeps increasing after the shutdown request, the plan is not reaching a graceful stop boundary. Save the log before using the abrupt stop client, because interrupted samplers may not write complete timing data.

  4. Check that no JMeter controller process remains. 
    $ pgrep -af ApacheJMeter.jar

    No output means the controller JVM has exited. If a process remains, check jmeter.log before sending another stop request.

  5. Generate a report from the stopped result file. 
    $ jmeter -g checkout-load.jtl -o stopped-run-report

    Use a new or empty output directory. A malformed or empty .jtl file stops report generation instead of creating index.html.

  6. Confirm that the report entry point exists. 
    $ ls stopped-run-report/index.html stopped-run-report/statistics.json
stopped-run-report/index.html
stopped-run-report/statistics.json