karatelabs/karate · error · RuntimeException

karate.match() needs at least one argument

Error message

karate.match() needs at least one argument

What it means

karate.match() exposed to JS requires at least one argument. With zero arguments there is nothing to match, so the JavaInvokable lambda in KarateJs.karateMatch() throws immediately before any evaluation. Karate supports two forms: karate.match(actual, expected) and the single-string form karate.match("foo == expected"); neither is valid empty.

Solutions

  1. Pass the match expression or both operands: karate.match(actual, expected) or karate.match('foo == expected').
  2. If arguments are built dynamically, guard for an empty list before calling and skip or throw a domain-specific error.
  3. Check the spread source isn't empty: karate.match(...parts) fails when parts = [].

Example fix

// before
karate.match();
// after
karate.match(response.status, 200);
// or single-string form
karate.match("response == { id: '#number' }");
Defensive patterns

Strategy: validation

Validate before calling

if (actual === undefined && expected === undefined) {
  throw new Error('karate.match needs a match expression or (actual, expected)');
}
var result = karate.match(actual, expected);

Type guard

function canMatch(args) { return Array.isArray(args) && args.length >= 1 && args[0] != null; }

Try / catch

var result;
try {
  result = karate.match(actual, expected);
} catch (e) {
  if (String(e.message).includes('needs at least one argument')) {
    result = { pass: false, message: 'match skipped: no operands provided' };
  } else { throw e; }
}

Prevention

When it happens

Trigger: Calling karate.match() with no arguments from JS — e.g. a typo like karate.match() instead of karate.match(actual, expected), or spreading an empty array: karate.match(...arr) where arr is empty.

Common situations: Dynamic argument construction (call sites that build the argument list programmatically and pass an empty list), copy-paste edits that removed the operands, or refactors that renamed variables leaving the call empty.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/KarateJs.java:647

                        target = new java.util.LinkedHashMap<>();
                        engine.put(name, target);
                    }
                    Json.of(target).set(path, value);
                }
            }
            return null;
        };
    }

    /**
     * V1-compatible karate.match() function.
     * Usage: karate.match(actual, expected) or karate.match("foo == expected")
     * Returns { pass: boolean, message: String|null }
     */
    private JavaInvokable karateMatch() {
        return args -> {
            if (args.length == 0) {
                throw new RuntimeException("karate.match() needs at least one argument");
            }
            if (args.length >= 2) {
                // Two-argument form: karate.match(actual, expected)
                // Do an equals comparison and return { pass, message }
                Object actual = args[0];
                Object expected = args[1];
                try (Value value = Match.evaluate(actual, null, null)) {
                    return value._equals(expected).toMap();
                }
            } else {
                // One-argument string form: karate.match("foo == expected").
                // Delegate to the same evaluator the `match` keyword uses so both operands
                // get identical handling — JsonPath ($-prefixed, wildcards), JSON literals,
                // embedded expressions, etc. Reusing StepExecutor.evalMatchString keeps the
                // JS API and the keyword from drifting (issue #2894).
                //
                // The string operands are resolved against the *currently executing*
                // scenario, not the scenario where this `karate` bridge was defined. A

View on GitHub (pinned to a22eb90246)