---
title: "JSR223 Sampler"
description: "Configure the JMeter JSR223 Sampler samplers: properties, defaults, and practical usage notes for building reliable load tests."
url: https://docs.jmeter.ai/components/jsr223-sampler/
lastUpdated: 2026-10-01
source: docs.jmeter.ai
---

# JSR223 Sampler

*Part of the **Samplers** category. Also documented in context in the [full Component Reference](/user-manual/component-reference/#jsr223-sampler).*

**TL;DR:** the JSR223 Sampler runs arbitrary Groovy (or other JSR223) code as the sample itself — useful for protocols JMeter has no built-in sampler for, or for generating a sample result around custom logic (crypto handshakes, SDK calls, batch simulation).

![JSR223 Sampler](/images/screenshots/jsr223-sampler.png)

The JSR223 Sampler allows JSR223 script code to be used to perform a sample or some computation required to create/update variables.

> **Note**
> If you don’t want to generate a [SampleResult](https://jmeter.apache.org/api/org/apache/jmeter/samplers/SampleResult.html) when this sampler is run, call the following method:
>
> ```plaintext
> SampleResult.setIgnore();
> ```
>
> This call will have the following impact:
>
> - SampleResult will not be delivered to SampleListeners like View Results Tree, Summariser …
> - SampleResult will not be evaluated in Assertions nor PostProcessors
> - SampleResult will be evaluated to computing last sample status (${JMeterThread.last_sample_ok}),     and ThreadGroup “Action to be taken after a Sampler error” (since JMeter 5.4)

The JSR223 test elements have a feature (compilation) that can significantly increase performance.
To benefit from this feature:

- Use Script files instead of inlining them. This will make JMeter compile them if this feature is available on ScriptEngine and cache them.
- Or Use Script Text and check `Cache compiled script if available` property.      :::note When using this feature, ensure your script code does not use JMeter variables or JMeter function calls directly in script code as caching would only cache first replacement. Instead use script parameters. :::      :::note To benefit from caching and compilation, the language engine used for scripting must implement JSR223 `[Compilable](https://docs.oracle.com/javase/8/docs/api/javax/script/Compilable.html)` interface (Groovy is one of these, java, beanshell and javascript are not) :::      :::note When using Groovy as scripting language and not checking `Cache compiled script if available` (while caching is recommended), you should set this JVM Property `-Dgroovy.use.classvalue=true`         due to a Groovy Memory leak as of version 2.4.6, see:          - [GROOVY-7683](https://issues.apache.org/jira/browse/GROOVY-7683) - [GROOVY-7591](https://issues.apache.org/jira/browse/GROOVY-7591) - [JDK-8136353](https://bugs.openjdk.java.net/browse/JDK-8136353) :::

Cache size is controlled by the following JMeter property (`jmeter.properties`):

```plaintext
jsr223.compiled_scripts_cache_size=100
```

> **Note**
> Unlike the [BeanShell Sampler](/components/beanshell-sampler/), the interpreter is not saved between invocations.

> **Note**
> JSR223 Test Elements using Script file or Script text + checked `Cache compiled script if available` are now compiled if ScriptEngine supports this feature, this enables great performance enhancements.

> **Note**
> JMeter processes function and variable references before passing the script field to the interpreter,
> so the references will only be resolved once.
> Variable and function references in script files will be passed
> verbatim to the interpreter, which is likely to cause a syntax error.
> In order to use runtime variables, please use the appropriate props methods,
> e.g.
>
> ```plaintext
> props.get("START.HMS");
> props.put("PROP1","1234");
> ```

| Name | Required | Description |
| --- | --- | --- |
| Name | No | Descriptive name for this sampler that is shown in the tree. |
| Scripting Language | Yes | Name of the JSR223 scripting language to be used.        :::note There are other languages supported than those that appear in the drop-down list.         Others may be available if the appropriate jar is installed in the JMeter lib directory.         Notice that some languages such as Velocity may use a different syntax for JSR223 variables,         e.g.  `bash $log.debug("Hello " + $vars.get("a")); `  for Velocity. ::: |
| Script File | No | Name of a file to be used as a JSR223 script, if a relative file path is used, then it will be relative to directory referenced by “`user.dir`” System property |
| Parameters | No | List of parameters to be passed to the script file or the script. |
| Cache compiled script if available | No | If checked (advised) and the language used supports `[Compilable](https://docs.oracle.com/javase/8/docs/api/javax/script/Compilable.html)` interface (Groovy is one of these, java, beanshell and javascript are not), JMeter will compile the Script and cache it using its MD5 hash as unique cache key |
| Script | Yes (unless script file is provided) | Script to be passed to JSR223 language |

If a script file is supplied, that will be used, otherwise the script will be used.

Before invoking the script, some variables are set up.
Note that these are JSR223 variables - i.e. they can be used directly in the script.

- `log` - the [Logger](https://www.slf4j.org/api/org/slf4j/Logger.html)
- `Label` - the Sampler label
- `FileName` - the file name, if any
- `Parameters` - text from the Parameters field
- `args` - the parameters, split as described above
- `SampleResult` - pointer to the current [SampleResult](https://jmeter.apache.org/api/org/apache/jmeter/samplers/SampleResult.html)
- `sampler` - ([Sampler](https://jmeter.apache.org/api/org/apache/jmeter/samplers/Sampler.html)) - pointer to current Sampler
- `ctx` - [JMeterContext](https://jmeter.apache.org/api/org/apache/jmeter/threads/JMeterContext.html)
- `vars` - [JMeterVariables](https://jmeter.apache.org/api/org/apache/jmeter/threads/JMeterVariables.html)  - e.g.    `vars.get("VAR1"); vars.put("VAR2","value"); vars.remove("VAR3"); vars.putObject("OBJ1",new Object());`
- `props` - JMeterProperties  (class [`java.util.Properties`](https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html)) - e.g.    `props.get("START.HMS"); props.put("PROP1","1234");`
- `OUT` - System.out - e.g. `OUT.println("message")`

The [SampleResult](https://jmeter.apache.org/api/org/apache/jmeter/samplers/SampleResult.html) ResponseData is set from the return value of the script.
If the script returns `null`, it can set the response directly, by using the method
`SampleResult.setResponseData(data)`, where data is either a String or a byte array.
The data type defaults to “`text`”, but can be set to binary by using the method
`SampleResult.setDataType(SampleResult.BINARY)`.

The SampleResult variable gives the script full access to all the fields and
methods in the SampleResult. For example, the script has access to the methods
`setStopThread(boolean)` and `setStopTest(boolean)`.

Unlike the BeanShell Sampler, the JSR223 Sampler does not set the `ResponseCode`, `ResponseMessage` and sample status via script variables.
Currently the only way to changes these is via the [SampleResult](https://jmeter.apache.org/api/org/apache/jmeter/samplers/SampleResult.html) methods:

- `SampleResult.setSuccessful(true/false)`
- `SampleResult.setResponseCode("code")`
- `SampleResult.setResponseMessage("message")`

### Common gotchas

- **Always use Groovy**, never BeanShell — Groovy is compiled and cached, BeanShell is interpreted fresh every iteration and is dramatically slower under load.
- Set `SampleResult.setSuccessful(false)` explicitly on failure paths; an uncaught exception marks the sample an error, but logic errors that don’t throw won’t fail the sample unless you say so.
- Cache expensive setup (compiled patterns, HTTP clients, parsed config) in a `bsh.shared` alternative — for Groovy, prefer a `Pre-Processor`-level one-time init or a static field, not per-iteration work.
- For full recipes (JWT decoding, HMAC signing, dynamic headers), see the [JSR223 Groovy Scripting Guide](/topics/jsr223-groovy-scripting-guide/) and the MCP `get_jsr223_recipe` tool.

## Related

- [API Load Testing Guide](/topics/api-load-testing/)
- [cURL & HAR to JMX Converter](/tools/curl-to-jmx/)
- [JSR223 Groovy Scripting Guide](/topics/jsr223-groovy-scripting-guide/)
- [JSR223 Groovy Script Errors](/topics/errors/jsr223-groovy-script-errors/)
- [Full Component Reference](/user-manual/component-reference/)
- [Functions and Variables](/user-manual/functions/)