--- title: "JMeter Error Playbooks" description: "Comprehensive directory of JMeter error playbooks: network exceptions, HTTP 5xx/4xx codes, OOM heap & native threads, JSR223 Groovy, and RMI troubleshooting." url: https://docs.jmeter.ai/topics/errors/ lastUpdated: 2026-10-01 source: docs.jmeter.ai --- # 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](/user-manual/best-practices/)). --- ## 1. Network, Connection & TLS Errors | Error Signature | Symptom / Description | Playbook | | --- | --- | --- | | `java.net.ConnectException` | Connection refused or TCP handshake timeout | [ConnectException](/topics/errors/connect-exception/) | | `java.net.SocketTimeoutException` | Server took too long to return data (`Read timed out`) | [SocketTimeoutException](/topics/errors/socket-timeout-exception/) | | `org.apache.http.NoHttpResponseException` | Server closed idle persistent Keep-Alive socket | [NoHttpResponseException](/topics/errors/no-http-response-exception/) | | `java.io.EOFException` | Premature EOF, unexpected end of file from server | [Premature EOF / Connection Aborted](/topics/errors/premature-eof-connection-abort/) | | `java.net.UnknownHostException` | Load injector DNS resolution failed | [UnknownHostException](/topics/errors/unknown-host-exception/) | | `java.net.BindException` | Ephemeral port exhaustion (`Address already in use`) | [BindException / Address in use](/topics/errors/bind-exception-address-in-use/) | | `javax.net.ssl.SSLHandshakeException` | PKIX path building failed, untrusted root CA | [SSLHandshakeException](/topics/errors/ssl-handshake-exception/) | | `javax.net.ssl.SSLPeerUnverifiedException` | Certificate hostname / SAN mismatch | [SSLPeerUnverifiedException](/topics/errors/ssl-peer-unverified/) | | `java.net.SocketException` | Socket closed, connection reset by peer, broken pipe | [Socket closed / connection reset](/topics/errors/socket-closed-connection-reset/) | | `Non HTTP response code` | General client-side wrapper for network exceptions | [Non HTTP response code](/topics/errors/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](/topics/errors/401-403-after-recording/) | | `HTTP 500 / 502 / 503 / 504` | Application crash, reverse proxy drop, or capacity overload | [HTTP 500, 502, 503, 504](/topics/errors/http-502-503-504/) | | `HTTP 415 / 400 Bad Request` | Missing `Content-Type: application/json` or bad payload | [HTTP 400 & 415 Errors](/topics/errors/http-415-400-bad-request/) | | `HTTP 429 / WAF 403 Block` | Cloudflare, AWS WAF, or rate limit threshold exceeded | [HTTP 429 & WAF Rate Limiting](/topics/errors/http-429-rate-limited/) | | `HTTP 407` | Proxy Authentication Required by a corporate forward proxy | [HTTP 407 Proxy Authentication](/topics/errors/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](/topics/errors/out-of-memory-heap/) | | `OutOfMemoryError: unable to create new native thread` | OS `ulimit -u` or PID capacity exhausted | [Native thread limit](/topics/errors/outofmemory-unable-to-create-native-thread/) | | `OutOfMemoryError: Metaspace & GC Overhead` | Groovy dynamic classloader leak or GC thrashing | [Metaspace & GC Overhead](/topics/errors/metaspace-gc-overhead-limit/) | | `SocketException: Too many open files` | OS file descriptor limit hit at high concurrency | [Too Many Open Files (ulimit)](/topics/errors/too-many-open-files-ulimit/) | | Throughput stuck / collapsing | Concurrency bottleneck or unpaced arrival rates | [Throughput stuck](/topics/errors/throughput-stuck/) | | JMeter Freezing & 100% CPU | GUI listener overhead or CLI hanging on test end | [Freezing, CPU & CLI Hangs](/topics/errors/jmeter-freeze-high-cpu-hanging/) | --- ## 4. Scripting, Dependencies & Correlation | Error Signature | Symptom / Description | Playbook | | --- | --- | --- | | `javax.script.ScriptException` | JSR223 Groovy syntax, MissingProperty, or null pointer | [JSR223 Groovy Errors](/topics/errors/jsr223-groovy-script-errors/) | | `ClassNotFoundException` | Missing JAR file in `lib/` (drivers) or `lib/ext/` (plugins) | [ClassNotFound & Missing JARs](/topics/errors/class-not-found-noclassdeffound/) | | `Error loading test plan` | Corrupt JMX, merge conflict markers, or version mismatch | [JMX Won’t Load / Corrupt Plan](/topics/errors/jmx-wont-load-corrupt-plan/) | | JSON/Regex returns `NOT_FOUND` | Extractor scoping, JSONPath syntax, or correlation bug | [Extractor Default Value](/topics/errors/extractor-not-found-default-value/) | | `CSV: File not found` & Sharing issues | Relative path resolution or duplicate data reading | [CSV Data Set & Sharing](/topics/errors/csv-data-set-file-not-found-sharing/) | | `Test failed: text expected to contain` | Response/JSON/Duration assertion mismatch or failed correlation | [Assertion Failed](/topics/errors/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](/topics/errors/rmi-connection-refused-remote-testing/) | | `Cannot create PoolableConnectionFactory` | JDBC database unreachable or connection pool exhausted | [JDBC Connection Pool Errors](/topics/errors/jdbc-connection-pool-errors/) | | Script works in GUI, fails in CLI | Path discrepancies, missing properties, or headless modes | [GUI works, CLI fails](/topics/errors/gui-works-cli-fails/) | | `Cannot generate HTML report` | Non-empty folder, clock skew, or timestamp corruption | [HTML Dashboard Errors](/topics/errors/html-dashboard-generation-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](/topics/errors/jmeter-wont-start-crash-on-launch/) | | Works in browser, fails in JMeter | Missing headers, cookies, redirects, or correlation gaps | [Works in Browser, Fails in JMeter](/topics/errors/works-in-browser-fails-in-jmeter/) | | Test stops early or unexpectedly | Scheduler duration, sampler error action, or JVM crash | [Test Stops Early / Unexpectedly](/topics/errors/test-stops-early-unexpectedly/) | --- ## Interactive Diagnostic Tools Use these interactive web tools on docs.jmeter.ai alongside the error playbooks: - [Heap & Memory Estimator](/tools/heap-estimator/) - Calculate optimal `-Xms`, `-Xmx`, and Metaspace parameters based on thread counts. - [Thread & Throughput Calculator](/tools/thread-calculator/) - Apply Little’s Law to calculate target concurrency from desired RPS and response time. - [CLI Command Builder](/tools/cli-builder/) - Generate production-ready non-GUI command lines with logging and property flags. - [Regex Extractor Builder](/tools/regex-tester/) - Validate regular expressions against response data without starting JMeter. - [Properties Cheat Sheet](/tools/properties-cheatsheet/) - 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](/topics/troubleshooting/) - [Best practices](/user-manual/best-practices/) - [API load testing](/topics/api-load-testing/) - [Distributed testing](/topics/distributed-testing/)