What causes "key cannot be null or blank" in karatelabs/karate?

Pass a non-blank variable name, e.g. new KarateSetBuilder("tokenId", session -> ...)

karatelabs/karate · error · IllegalArgumentException

key cannot be null or blank

Error message

key cannot be null or blank

What it means

KarateSetBuilder(key, valueSupplier) defines a Gatling session variable to set from Karate results. The variable name (key) is mandatory: null or blank keys are rejected with IllegalArgumentException before the supplier is validated.

Solutions

Pass a non-blank variable name, e.g. new KarateSetBuilder("tokenId", session -> ...)
Validate the config/property supplying the key before constructing the builder
Also ensure valueSupplier is non-null — it is checked next

Example fix

// before
String key = props.getProperty("set.key"); // missing -> null
new KarateSetBuilder(key, s -> s.get("response"));
// after
String key = props.getProperty("set.key", "tokenId");
new KarateSetBuilder(key, s -> s.get("response"));

Defensive patterns

Strategy: validation

Validate before calling

if (key == null || key.isBlank()) { throw new IllegalArgumentException("set key must be non-blank"); }
if (supplier == null) { throw new IllegalArgumentException("supplier must be non-null"); }

Try / catch

try {
  new KarateSetBuilder(key, supplier);
} catch (IllegalArgumentException e) {
  throw new IllegalStateException("Bad KarateSetBuilder config: " + e.getMessage(), e);
}

Prevention

Hardcode or default the variable name instead of reading it from optional config
Validate key and supplier together before constructing
Use Java's Objects.requireNonNull / isBlank checks upstream

When it happens

Trigger: new KarateSetBuilder(null, fn) or new KarateSetBuilder("", fn) / " ", typically when the key is built dynamically from an empty config value or a typo leaves it unset.

Common situations: Reading the variable name from a properties file that lacks the entry; string concatenation producing an empty name; refactoring where the literal key was deleted.

Related errors

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/720578e91713e153. Report an issue: GitHub.

Appendix: source

Thrown at karate-gatling/src/main/java/io/karatelabs/gatling/KarateSetBuilder.java:56

 *     .feed(feeder)
 *     .exec(karateSet("userId", s -&gt; s.getInt("id")))
 *     .exec(karateFeature("classpath:features/user.feature"))
 * </pre>
 */
public final class KarateSetBuilder implements ActionBuilder {

    private final String key;
    private final Function<Session, Object> valueSupplier;

    /**
     * Create a builder that sets a session variable.
     *
     * @param key the variable name
     * @param valueSupplier function to compute the value from the session
     */
    public KarateSetBuilder(String key, Function<Session, Object> valueSupplier) {
        if (key == null || key.isBlank()) {
            throw new IllegalArgumentException("key cannot be null or blank");
        }
        if (valueSupplier == null) {
            throw new IllegalArgumentException("valueSupplier cannot be null");
        }
        this.key = key;
        this.valueSupplier = valueSupplier;
    }

    /**
     * Convert to a session function for use with Gatling's exec().
     */
    public Function<Session, Session> toSessionFunction() {
        KarateSetAction action = new KarateSetAction(key, valueSupplier);
        return action.toSessionFunction();
    }

    @Override
    public io.gatling.core.action.builder.ActionBuilder asScala() {

View on GitHub (pinned to a22eb90246)