JMeter Won't Start or Crashes on Launch

JMeter Won’t Start or Crashes on Launch

Symptom

Double-clicking jmeter.bat (Windows) or jmeter.sh (Linux/macOS) produces one of these behaviors:

The window appears for a fraction of a second, then closes by itself.

Or the terminal shows one of these errors:

'java' is not recognized as an internal or external command

java.lang.UnsupportedClassVersionError: org/apache/jmeter/NewDriver

Error occurred during initialization of VM
Could not reserve enough space for object heap

Error: Could not find or load main class org.apache.jmeter.NewDriver

Quick diagnosis (TL;DR)

JMeter is a Java application, so startup failures almost always come from the JVM environment, not from the test plan: Java is missing from the PATH, the installed Java version is unsupported, or the requested heap is larger than the machine’s memory. Launch JMeter from a terminal instead of double-clicking, because the terminal shows the real error that the GUI hides.

Common causes

Cause	Specific Error	Why it happens
Java not installed or not on PATH	'java' is not recognized	No JDK/JRE installed, or JAVA_HOME/PATH not set
Java version too old	UnsupportedClassVersionError	JMeter 5.x requires Java 8 or newer; an older runtime cannot load the classes
Heap larger than available memory	Could not reserve enough space for object heap	JVM_ARGS or HEAP requests more RAM than the machine has
Incomplete or corrupt installation	Could not find or load main class org.apache.jmeter.NewDriver	Missing files from a partial unzip or a broken copy
macOS Gatekeeper block	”cannot be opened because the developer cannot be verified”	The downloaded archive carries a quarantine attribute

Fix (ordered)

1. Launch from a terminal to see the real error

The GUI swallows startup errors. Open a terminal in the JMeter bin/ directory and run:

# Linux / macOS
cd /path/to/jmeter/bin
./jmeter

# Windows (cmd.exe)
cd C:\path\to\jmeter\bin
jmeter.bat

The stack trace printed here tells you which of the fixes below applies.

2. Verify the Java version

JMeter 5.6 requires Java 8 or newer; a current LTS JDK such as 17 or 21 is recommended for load generators.

java -version

If the command is not found, install a JDK (for example Eclipse Temurin) and open a new terminal so the PATH update takes effect. If the version is older than 8, upgrade: the UnsupportedClassVersionError disappears once a supported runtime starts JMeter.

3. Fix the JVM heap reservation

The startup scripts default to -Xms1g -Xmx1g -XX:MaxMetaspaceSize=256m, which is read from the JVM_ARGS (Linux/macOS) or HEAP (Windows) environment variables. If someone raised these beyond the machine’s physical memory, the JVM refuses to start. Start JMeter with a sane heap:

# Linux / macOS: heap for this launch only
JVM_ARGS="-Xms1g -Xmx2g" ./jmeter

# Windows (cmd.exe)
set HEAP=-Xms1g -Xmx2g
jmeter.bat

Keep -Xmx below the machine’s free physical RAM. For heap sizing on real load tests, use the Heap & Memory Estimator.

4. Reinstall cleanly

Could not find or load main class org.apache.jmeter.NewDriver means files are missing. Download the full archive from jmeter.apache.org, extract it completely, and confirm that bin/ApacheJMeter.jar exists. Avoid extracting into folders synced or locked by security software.

5. macOS: clear the quarantine attribute

If macOS refuses to open JMeter after download:

xattr -d com.apple.quarantine /path/to/jmeter
chmod +x /path/to/jmeter/bin/jmeter.sh

Alternatively, right-click the launcher and choose Open, then confirm the prompt once.

6. Docker and CI containers

In containers the same JVM rules apply, plus two extras: set JAVA_HOME explicitly in the image, and pass the heap through the container’s environment rather than editing the scripts:

docker run -e JVM_ARGS="-Xms1g -Xmx2g" -v $(pwd):/jmx jmeter -n -t /jmx/plan.jmx -l /jmx/results.jtl

A container killed at startup with exit code 137 was OOM-killed by the orchestrator: raise the container memory limit or lower -Xmx. See Docker / Kubernetes for full setup.

Related tools and topics

Resource	Use when
Download JMeter	Getting a clean, current installation
Heap & Memory Estimator	Calculating -Xms, -Xmx, and Metaspace for real load
CLI Command Builder	Building correct non-GUI launch commands
OutOfMemoryError heap	JMeter starts but dies during the test
GUI works, CLI fails	Startup is fine but the CLI run behaves differently

Frequently asked questions

Why does the JMeter window flash and close immediately?

The GUI hides console errors, so a failed startup looks like a window that closes itself. Launch jmeter.bat or ./jmeter from a terminal: the printed stack trace names the actual cause, usually Java, heap, or a broken installation.

Which Java version does JMeter need?

JMeter 5.x requires Java 8 or newer, and a current LTS JDK such as 17 or 21 is recommended for load generators. Verify with java -version and install a JDK if the command is missing.

How do I give JMeter more memory if it won’t start?

The startup scripts read -Xms1g -Xmx1g defaults from the JVM_ARGS (Linux/macOS) or HEAP (Windows) environment variables. Set them to values your machine actually has before launching, for example JVM_ARGS="-Xms1g -Xmx2g" ./jmeter.

Can a corrupt test plan stop JMeter from starting?

No. Test plans load after startup, so a broken JMX cannot prevent the GUI from opening. If JMeter itself does not open, the cause is the Java runtime, the heap, or the installation, not the plan.

Continue Learning

→

Next Practical Step

Run JMeter from a terminal, note the exact error, then apply the matching fix above before retrying the GUI.

📖

Related Reference

• JMeter for beginners
• Docker / Kubernetes
• CI/CD load testing
• Troubleshooting overview