JMeter Error Playbooks

JMeter Error Playbooks

A grounded, symptom-based directory of dedicated playbooks for every error, exception, and bottleneck encountered when running Apache JMeter.

Each playbook follows an identical structure:

1. Symptom & Exact Signature - Real stack traces and messages from jmeter.log, View Results Tree, and JTL outputs.
2. Quick Diagnosis (TL;DR) - Direct 2-sentence summary for immediate triage.
3. Common Causes - Root cause breakdown explaining underlying network, JVM, or protocol behavior.
4. Ordered Fixes - Practical, copy-pasteable configuration snippets, CLI commands, and properties.
5. Interactive Tools & Related Guides - Direct bridges to calculators, cheat sheets, and manual sections.

Standard Triage Protocol

Before running large-scale tests, always debug with 1 thread and 1 loop in GUI mode with View Results Tree enabled. Once the script succeeds cleanly, disable all visual listeners and run in CLI mode (best practices).

---

1. Network, Connection & TLS Errors

Error Signature	Symptom / Description	Playbook
java.net.ConnectException	Connection refused or TCP handshake timeout	ConnectException
java.net.SocketTimeoutException	Server took too long to return data (Read timed out)	SocketTimeoutException
org.apache.http.NoHttpResponseException	Server closed idle persistent Keep-Alive socket	NoHttpResponseException
java.io.EOFException	Premature EOF, unexpected end of file from server	Premature EOF / Connection Aborted
java.net.UnknownHostException	Load injector DNS resolution failed	UnknownHostException
java.net.BindException	Ephemeral port exhaustion (Address already in use)	BindException / Address in use
javax.net.ssl.SSLHandshakeException	PKIX path building failed, untrusted root CA	SSLHandshakeException
javax.net.ssl.SSLPeerUnverifiedException	Certificate hostname / SAN mismatch	SSLPeerUnverifiedException
java.net.SocketException	Socket closed, connection reset by peer, broken pipe	Socket closed / connection reset
Non HTTP response code	General client-side wrapper for network exceptions	Non HTTP response code

---

2. HTTP Status Codes & API Request Errors

Error Signature	Symptom / Description	Playbook
HTTP 401 / 403 after recording	Missing dynamic CSRF, OAuth token, or session cookie	401/403 after recording
HTTP 500 / 502 / 503 / 504	Application crash, reverse proxy drop, or capacity overload	HTTP 500, 502, 503, 504
HTTP 415 / 400 Bad Request	Missing Content-Type: application/json or bad payload	HTTP 400 & 415 Errors
HTTP 429 / WAF 403 Block	Cloudflare, AWS WAF, or rate limit threshold exceeded	HTTP 429 & WAF Rate Limiting
HTTP 407	Proxy Authentication Required by a corporate forward proxy	HTTP 407 Proxy Authentication

---

3. JVM, Memory & Thread Resource Exhaustion

Error Signature	Symptom / Description	Playbook
OutOfMemoryError: Java heap space	Heap memory filled with listener data or buffers	OutOfMemoryError heap
OutOfMemoryError: unable to create new native thread	OS ulimit -u or PID capacity exhausted	Native thread limit
OutOfMemoryError: Metaspace & GC Overhead	Groovy dynamic classloader leak or GC thrashing	Metaspace & GC Overhead
SocketException: Too many open files	OS file descriptor limit hit at high concurrency	Too Many Open Files (ulimit)
Throughput stuck / collapsing	Concurrency bottleneck or unpaced arrival rates	Throughput stuck
JMeter Freezing & 100% CPU	GUI listener overhead or CLI hanging on test end	Freezing, CPU & CLI Hangs

---

4. Scripting, Dependencies & Correlation

Error Signature	Symptom / Description	Playbook
javax.script.ScriptException	JSR223 Groovy syntax, MissingProperty, or null pointer	JSR223 Groovy Errors
ClassNotFoundException	Missing JAR file in lib/ (drivers) or lib/ext/ (plugins)	ClassNotFound & Missing JARs
Error loading test plan	Corrupt JMX, merge conflict markers, or version mismatch	JMX Won’t Load / Corrupt Plan
JSON/Regex returns NOT_FOUND	Extractor scoping, JSONPath syntax, or correlation bug	Extractor Default Value
CSV: File not found & Sharing issues	Relative path resolution or duplicate data reading	CSV Data Set & Sharing
Test failed: text expected to contain	Response/JSON/Duration assertion mismatch or failed correlation	Assertion Failed

---

5. Distributed Testing, Databases & Reporting

Error Signature	Symptom / Description	Playbook
RMI Connection refused to host: 127.0.0.1	Remote worker loopback binding or SSL keystore error	Distributed RMI Errors
Cannot create PoolableConnectionFactory	JDBC database unreachable or connection pool exhausted	JDBC Connection Pool Errors
Script works in GUI, fails in CLI	Path discrepancies, missing properties, or headless modes	GUI works, CLI fails
Cannot generate HTML report	Non-empty folder, clock skew, or timestamp corruption	HTML Dashboard Errors

---

6. Startup & Test Execution Behavior

Error Signature	Symptom / Description	Playbook
JMeter window flashes and closes	Startup crash from Java, heap, or installation problems	JMeter Won’t Start / Crash on Launch
Works in browser, fails in JMeter	Missing headers, cookies, redirects, or correlation gaps	Works in Browser, Fails in JMeter
Test stops early or unexpectedly	Scheduler duration, sampler error action, or JVM crash	Test Stops Early / Unexpectedly

---

Interactive Diagnostic Tools

Use these interactive web tools on docs.jmeter.ai alongside the error playbooks:

• Heap & Memory Estimator - Calculate optimal -Xms, -Xmx, and Metaspace parameters based on thread counts.
• Thread & Throughput Calculator - Apply Little’s Law to calculate target concurrency from desired RPS and response time.
• CLI Command Builder - Generate production-ready non-GUI command lines with logging and property flags.
• Regex Extractor Builder - Validate regular expressions against response data without starting JMeter.
• Properties Cheat Sheet - Searchable catalog of all jmeter.properties and user.properties.

Continue Learning

→

Next Practical Step

Select the playbook matching your error message or exception above to view root causes and ordered fixes.

📖

Related Reference

• Troubleshooting overview
• Best practices
• API load testing
• Distributed testing